@optique/prompt 1.3.0-dev.2411 → 1.3.0-dev.2418

package/dist/index.cjs

@@ -22,10 +22,117 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_dependency = __toESM(require("@optique/core/dependency"));
+const __optique_core_message = __toESM(require("@optique/core/message"));
 const __optique_core_extension = __toESM(require("@optique/core/extension"));
 const __optique_core_fluent = __toESM(require("@optique/core/fluent"));
 
 //#region src/index.ts
+const derivedPromptConfigMarker = Symbol.for("@optique/prompt/derivedPromptConfig");
+/**
+* Checks whether a prompt configuration was created by
+* {@link derivePromptConfig}.
+*
+* @param config The configuration to inspect.
+* @returns `true` for a derived prompt configuration.
+* @since 1.3.0
+*/
+function isDerivedPromptConfig(config) {
+	return config != null && typeof config === "object" && derivedPromptConfigMarker in config && config[derivedPromptConfigMarker] === true;
+}
+function derivePromptConfig(source, resolver, options) {
+	const isTuple = Array.isArray(source);
+	const dependencies = isTuple ? source : [source];
+	if (dependencies.length === 0) throw new TypeError("derivePromptConfig() requires at least one dependency source.");
+	const infos = dependencies.map(__optique_core_dependency.getDependencySourceInfo);
+	const singleDefault = options?.defaultValue;
+	const defaultValues = isTuple ? options?.defaultValues : singleDefault == null ? void 0 : () => [singleDefault()];
+	const resolve = isTuple ? (values, usedDefaults) => resolver(values, { usedDefaults }) : (values, usedDefaults) => resolver(values[0], { usedDefault: usedDefaults[0] });
+	return {
+		[derivedPromptConfigMarker]: true,
+		dependencies,
+		dependencyIds: infos.map((info) => info.sourceId),
+		dependencyLabels: infos.map((info, index) => info.metavar ?? `dependency #${index + 1}`),
+		resolve,
+		...defaultValues == null ? {} : { defaultValues },
+		...options?.when == null ? {} : {
+			when: options.when,
+			otherwise: options.otherwise
+		}
+	};
+}
+function describeThrown(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Resolves a derived prompt configuration against the dependency runtime.
+*
+* A failed upstream source fails the resolution transitively—the resolver
+* and the adapter never run.  A missing source uses the configuration's
+* declared default, or fails when none is declared.  Resolver exceptions
+* (synchronous throws and rejections alike) become prompt failures so
+* the scheduler treats them like a cancelled prompt.
+*/
+async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel) {
+	const runtime = exec?.dependencyRuntime;
+	const ids = config.dependencyIds;
+	if (runtime != null) {
+		const failedIndex = ids.findIndex((id) => runtime.isSourceFailed(id));
+		if (failedIndex >= 0) {
+			runtime.propagateSourceFailure(ids, ownLabel ?? "prompt", ownSourceId);
+			const base = __optique_core_message.message`Cannot resolve prompt configuration: dependency ${config.dependencyLabels[failedIndex]} failed.`;
+			const chain = ownSourceId == null ? runtime.getSourceFailureChain(ids[failedIndex]) : void 0;
+			return {
+				ok: false,
+				error: chain == null || chain.length < 2 ? base : __optique_core_message.message`${base} Dependency chain: ${chain.join(" -> ")}.`
+			};
+		}
+	}
+	const missing = [];
+	const values = ids.map((id, index) => {
+		if (runtime?.hasSource(id) === true) return runtime.getSource(id);
+		missing.push(index);
+		return void 0;
+	});
+	const usedDefaults = ids.map(() => false);
+	if (missing.length > 0) {
+		if (config.defaultValues == null) {
+			const missingLabels = (0, __optique_core_message.values)(missing.map((index) => config.dependencyLabels[index]));
+			return {
+				ok: false,
+				error: missing.length > 1 ? __optique_core_message.message`Cannot resolve prompt configuration: dependencies ${missingLabels} are not available and no default values are declared.` : __optique_core_message.message`Cannot resolve prompt configuration: dependency ${missingLabels} is not available and no default value is declared.`
+			};
+		}
+		let defaults;
+		try {
+			defaults = config.defaultValues();
+		} catch (error) {
+			return {
+				ok: false,
+				error: __optique_core_message.message`Prompt configuration default evaluation failed: ${describeThrown(error)}`
+			};
+		}
+		if (defaults.length !== ids.length) return {
+			ok: false,
+			error: __optique_core_message.message`Prompt configuration declared ${String(defaults.length)} default values for ${String(ids.length)} dependencies.`
+		};
+		for (const index of missing) {
+			values[index] = defaults[index];
+			usedDefaults[index] = true;
+		}
+	}
+	try {
+		return {
+			ok: true,
+			config: await config.resolve(values, usedDefaults)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: __optique_core_message.message`Prompt configuration resolution failed: ${describeThrown(error)}`
+		};
+	}
+}
 function shouldDeferPrompt(parser, state, exec) {
 	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state, exec) === true;
 }
@@ -60,6 +167,7 @@ function hasSourceBindingMarker(state) {
 	return state != null && typeof state === "object" && "hasCliValue" in state && Object.getOwnPropertySymbols(state).length > 0;
 }
 function readDefaultValue(adapter, config) {
+	if (isDerivedPromptConfig(config)) return void 0;
 	if (adapter.getDefaultValue != null) return adapter.getDefaultValue(config);
 	if (config != null && typeof config === "object" && "default" in config) return config.default;
 	return void 0;
@@ -82,7 +190,8 @@ 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.
+*          parser.  The configuration may be a static `TConfig` or a
+*          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
 * @since 1.2.0
 */
 function createPromptAdapter(adapter) {
@@ -131,12 +240,19 @@ function createPromptAdapter(adapter) {
 			if (cliStateIsInjectedAnnotationWrapper && requiresSourceBindingForAnnotationWrapper) return hasNestedSourceBinding;
 			return shouldAttemptInnerCompletion(cliState, state) || hasNestedSourceBinding;
 		}
-		async function executePrompt() {
+		async function executePrompt(exec) {
 			if (config.when != null && !await config.when()) return {
 				success: true,
 				value: config.otherwise
 			};
-			return adapter.execute(config);
+			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);
 		}
 		const parserInheritsAnnotations = (0, __optique_core_extension.getTraits)(parser).inheritsAnnotations === true;
 		const promptedParser = {
@@ -247,13 +363,15 @@ function createPromptAdapter(adapter) {
 							return Promise.resolve(cached);
 						}
 						if (session.policy === "demand-only" && !session.demanded.has(sourceId)) return Promise.resolve(deferredPromptResult(readPlaceholder()));
-						return executePrompt().then((result) => {
+						if (session.policy === "demand-only" && isDerivedPromptConfig(config) && config.dependencyIds.some((id) => exec?.dependencyRuntime?.hasSource(id) !== true && exec?.dependencyRuntime?.isSourceFailed(id) !== true)) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+						return executePrompt(exec).then((result) => {
 							session.results.set(cacheKey, result);
 							session.effectfulSources.add(sourceId);
 							return result;
 						});
 					}
-					return executePrompt();
+					if (session?.policy === "demand-only" && isDerivedPromptConfig(config)) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+					return executePrompt(exec);
 				};
 				const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
 				const decideFromParse = (parseResult) => {
@@ -337,8 +455,12 @@ function createPromptAdapter(adapter) {
 			},
 			completeSource: source.preservesSourceValue === false ? void 0 : (state, exec) => promptedParser.complete(state, exec)
 		}));
-		if (dependencyMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
-			value: dependencyMetadata,
+		const composedMetadata = isDerivedPromptConfig(config) ? {
+			...dependencyMetadata ?? {},
+			completion: { dependencyIds: config.dependencyIds }
+		} : dependencyMetadata;
+		if (composedMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
+			value: composedMetadata,
 			configurable: true,
 			enumerable: false
 		});
@@ -347,4 +469,6 @@ function createPromptAdapter(adapter) {
 }
 
 //#endregion
-exports.createPromptAdapter = createPromptAdapter;
+exports.createPromptAdapter = createPromptAdapter;
+exports.derivePromptConfig = derivePromptConfig;
+exports.isDerivedPromptConfig = isDerivedPromptConfig;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { AnyDependencySource, DependencyValue, DependencyValues } from "@optique/core/dependency";
 import { FluentParser } from "@optique/core/fluent";
 import { Mode, Parser } from "@optique/core/parser";
 import { ValueParserResult } from "@optique/core/valueparser";
@@ -57,6 +58,175 @@ interface PromptAdapter<TConfig> {
    */
   readonly getDefaultValue?: (config: TConfig) => unknown;
 }
+declare const derivedPromptConfigMarker: unique symbol;
+/**
+ * Context passed to a single-dependency prompt configuration resolver.
+ *
+ * @since 1.3.0
+ */
+interface DerivePromptConfigContext {
+  /**
+   * Whether the dependency value came from the `defaultValue` declared by
+   * this derived prompt configuration rather than a published source
+   * value.  Source-level fallbacks such as `withDefault()` publish real
+   * values and are not reported here.
+   */
+  readonly usedDefault: boolean;
+}
+/**
+ * Context passed to a multi-dependency prompt configuration resolver.
+ *
+ * @typeParam Deps Tuple of dependency sources the resolver reads.
+ * @since 1.3.0
+ */
+interface DerivePromptConfigsContext<Deps extends readonly AnyDependencySource[]> {
+  /**
+   * For each dependency position, whether the value came from the
+   * `defaultValues` declared by this derived prompt configuration rather
+   * than a published source value.
+   */
+  readonly usedDefaults: { readonly [K in keyof Deps]: boolean };
+}
+/**
+ * Options for a single-dependency {@link derivePromptConfig} call.
+ *
+ * @typeParam TDefault Value type of the dependency source.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.3.0
+ */
+type DerivePromptConfigOptions<TDefault, TOtherwise> = {
+  /**
+   * Lazily evaluated fallback used when the dependency source has not
+   * published a value.  Without it, an unresolved dependency fails the
+   * prompt instead of running the resolver.
+   */
+  readonly defaultValue?: () => TDefault;
+} & ({
+  readonly when?: never;
+  readonly otherwise?: never;
+} | {
+  readonly when: () => boolean | Promise<boolean>;
+  readonly otherwise: TOtherwise;
+});
+/**
+ * Options for a multi-dependency {@link derivePromptConfig} call.
+ *
+ * @typeParam TDefaults Tuple of dependency source value types.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.3.0
+ */
+type DerivePromptConfigsOptions<TDefaults extends readonly unknown[], TOtherwise> = {
+  /**
+   * Lazily evaluated fallbacks used for dependency sources that have
+   * not published a value.  The thunk must return one value per
+   * dependency.  Without it, an unresolved dependency fails the prompt
+   * instead of running the resolver.
+   */
+  readonly defaultValues?: () => TDefaults;
+} & ({
+  readonly when?: never;
+  readonly otherwise?: never;
+} | {
+  readonly when: () => boolean | Promise<boolean>;
+  readonly otherwise: TOtherwise;
+});
+/**
+ * A prompt configuration derived from dependency source values, created
+ * by {@link derivePromptConfig}.
+ *
+ * The resolver runs during the real completion phase, immediately before
+ * the adapter executes, and never during probes, help, or suggestions.
+ * Generated documentation therefore cannot reflect a derived
+ * configuration and falls back to the wrapped parser's static metadata.
+ *
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.3.0
+ */
+interface DerivedPromptConfig<TConfig, TOtherwise = never> {
+  readonly [derivedPromptConfigMarker]: true;
+  /** The dependency sources the resolver reads, in declaration order. */
+  readonly dependencies: readonly AnyDependencySource[];
+  /** Snapshot of the dependency source identities. @internal */
+  readonly dependencyIds: readonly symbol[];
+  /** Diagnostic labels matching {@link dependencyIds}. @internal */
+  readonly dependencyLabels: readonly string[];
+  /**
+   * Resolves the adapter configuration from dependency values.  Receives
+   * one value and one used-default flag per dependency position.
+   * @internal
+   */
+  readonly resolve: (values: readonly unknown[], usedDefaults: readonly boolean[]) => TConfig | Promise<TConfig>;
+  /**
+   * Lazily evaluated fallbacks, one per dependency position.
+   * @internal
+   */
+  readonly defaultValues?: () => readonly unknown[];
+  /** Runtime condition, evaluated before the resolver. */
+  readonly when?: () => boolean | Promise<boolean>;
+  /** Value produced when {@link when} returns `false`. */
+  readonly otherwise?: TOtherwise;
+}
+/**
+ * Checks whether a prompt configuration was created by
+ * {@link derivePromptConfig}.
+ *
+ * @param config The configuration to inspect.
+ * @returns `true` for a derived prompt configuration.
+ * @since 1.3.0
+ */
+declare function isDerivedPromptConfig(config: unknown): config is DerivedPromptConfig<unknown, unknown>;
+/**
+ * Derives a prompt configuration from one dependency source value.
+ *
+ * The resolver may return the configuration synchronously or
+ * asynchronously.  It runs only during the real completion phase, after
+ * the named source has published its value—whether that value came from
+ * the command line, a source binding, or another prompt.
+ *
+ * @typeParam D The dependency source type.
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @param source The dependency source the resolver reads.
+ * @param resolver Produces the adapter configuration from the source
+ *                 value.
+ * @param options Optional declared default and runtime condition.
+ * @returns A derived configuration accepted by `prompt()` wrappers.
+ * @throws {TypeError} If `source` is not a dependency source.
+ * @since 1.3.0
+ */
+declare function derivePromptConfig<D extends AnyDependencySource, TConfig, const TOtherwise = never>(source: D, resolver: (value: DependencyValue<D>, context: DerivePromptConfigContext) => TConfig | Promise<TConfig>, options?: DerivePromptConfigOptions<DependencyValue<D>, TOtherwise>): DerivedPromptConfig<TConfig, TOtherwise>;
+/**
+ * Derives a prompt configuration from multiple dependency source values.
+ *
+ * The resolver receives the values as a tuple matching the declaration
+ * order of `sources`.  Evaluation order among prompts follows the
+ * dependency graph, not surrounding object or tuple field order.
+ *
+ * @typeParam Deps Tuple of dependency sources the resolver reads.
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @param sources The dependency sources, at least one.
+ * @param resolver Produces the adapter configuration from the source
+ *                 values.
+ * @param options Optional declared defaults and runtime condition.
+ * @returns A derived configuration accepted by `prompt()` wrappers.
+ * @throws {TypeError} If `sources` is empty or contains a value that is
+ *         not a dependency source.
+ * @since 1.3.0
+ */
+declare function derivePromptConfig<const Deps extends readonly [AnyDependencySource, ...AnyDependencySource[]], TConfig, const TOtherwise = never>(sources: Deps, resolver: (values: DependencyValues<Deps>, context: DerivePromptConfigsContext<Deps>) => TConfig | Promise<TConfig>, options?: DerivePromptConfigsOptions<DependencyValues<Deps>, TOtherwise>): DerivedPromptConfig<TConfig, TOtherwise>;
+/**
+ * Prompt configuration accepted by a generated `prompt()` wrapper: either
+ * a static adapter configuration (optionally with a runtime condition) or
+ * a configuration derived from dependency sources via
+ * {@link derivePromptConfig}.
+ *
+ * @typeParam TConfig Prompt configuration accepted by the adapter.
+ * @typeParam TValue Value type produced by the wrapped parser.
+ * @since 1.3.0
+ */
+type PromptConfigInput<TConfig, TValue> = (TConfig & PromptCondition<TValue>) | DerivedPromptConfig<TConfig, NoInfer<TValue>>;
 /**
  * Creates a `prompt()` parser wrapper for a prompt library adapter.
  *
@@ -68,9 +238,10 @@ interface PromptAdapter<TConfig> {
  * @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.
+ *          parser.  The configuration may be a static `TConfig` or a
+ *          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
  * @since 1.2.0
  */
-declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: TConfig & PromptCondition<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>) => FluentParser<"async", TValue, TState>;
 //#endregion
-export { PromptAdapter, PromptCondition, createPromptAdapter };
+export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { AnyDependencySource, DependencyValue, DependencyValues } from "@optique/core/dependency";
 import { FluentParser } from "@optique/core/fluent";
 import { Mode, Parser } from "@optique/core/parser";
 import { ValueParserResult } from "@optique/core/valueparser";
@@ -57,6 +58,175 @@ interface PromptAdapter<TConfig> {
    */
   readonly getDefaultValue?: (config: TConfig) => unknown;
 }
+declare const derivedPromptConfigMarker: unique symbol;
+/**
+ * Context passed to a single-dependency prompt configuration resolver.
+ *
+ * @since 1.3.0
+ */
+interface DerivePromptConfigContext {
+  /**
+   * Whether the dependency value came from the `defaultValue` declared by
+   * this derived prompt configuration rather than a published source
+   * value.  Source-level fallbacks such as `withDefault()` publish real
+   * values and are not reported here.
+   */
+  readonly usedDefault: boolean;
+}
+/**
+ * Context passed to a multi-dependency prompt configuration resolver.
+ *
+ * @typeParam Deps Tuple of dependency sources the resolver reads.
+ * @since 1.3.0
+ */
+interface DerivePromptConfigsContext<Deps extends readonly AnyDependencySource[]> {
+  /**
+   * For each dependency position, whether the value came from the
+   * `defaultValues` declared by this derived prompt configuration rather
+   * than a published source value.
+   */
+  readonly usedDefaults: { readonly [K in keyof Deps]: boolean };
+}
+/**
+ * Options for a single-dependency {@link derivePromptConfig} call.
+ *
+ * @typeParam TDefault Value type of the dependency source.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.3.0
+ */
+type DerivePromptConfigOptions<TDefault, TOtherwise> = {
+  /**
+   * Lazily evaluated fallback used when the dependency source has not
+   * published a value.  Without it, an unresolved dependency fails the
+   * prompt instead of running the resolver.
+   */
+  readonly defaultValue?: () => TDefault;
+} & ({
+  readonly when?: never;
+  readonly otherwise?: never;
+} | {
+  readonly when: () => boolean | Promise<boolean>;
+  readonly otherwise: TOtherwise;
+});
+/**
+ * Options for a multi-dependency {@link derivePromptConfig} call.
+ *
+ * @typeParam TDefaults Tuple of dependency source value types.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.3.0
+ */
+type DerivePromptConfigsOptions<TDefaults extends readonly unknown[], TOtherwise> = {
+  /**
+   * Lazily evaluated fallbacks used for dependency sources that have
+   * not published a value.  The thunk must return one value per
+   * dependency.  Without it, an unresolved dependency fails the prompt
+   * instead of running the resolver.
+   */
+  readonly defaultValues?: () => TDefaults;
+} & ({
+  readonly when?: never;
+  readonly otherwise?: never;
+} | {
+  readonly when: () => boolean | Promise<boolean>;
+  readonly otherwise: TOtherwise;
+});
+/**
+ * A prompt configuration derived from dependency source values, created
+ * by {@link derivePromptConfig}.
+ *
+ * The resolver runs during the real completion phase, immediately before
+ * the adapter executes, and never during probes, help, or suggestions.
+ * Generated documentation therefore cannot reflect a derived
+ * configuration and falls back to the wrapped parser's static metadata.
+ *
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @since 1.3.0
+ */
+interface DerivedPromptConfig<TConfig, TOtherwise = never> {
+  readonly [derivedPromptConfigMarker]: true;
+  /** The dependency sources the resolver reads, in declaration order. */
+  readonly dependencies: readonly AnyDependencySource[];
+  /** Snapshot of the dependency source identities. @internal */
+  readonly dependencyIds: readonly symbol[];
+  /** Diagnostic labels matching {@link dependencyIds}. @internal */
+  readonly dependencyLabels: readonly string[];
+  /**
+   * Resolves the adapter configuration from dependency values.  Receives
+   * one value and one used-default flag per dependency position.
+   * @internal
+   */
+  readonly resolve: (values: readonly unknown[], usedDefaults: readonly boolean[]) => TConfig | Promise<TConfig>;
+  /**
+   * Lazily evaluated fallbacks, one per dependency position.
+   * @internal
+   */
+  readonly defaultValues?: () => readonly unknown[];
+  /** Runtime condition, evaluated before the resolver. */
+  readonly when?: () => boolean | Promise<boolean>;
+  /** Value produced when {@link when} returns `false`. */
+  readonly otherwise?: TOtherwise;
+}
+/**
+ * Checks whether a prompt configuration was created by
+ * {@link derivePromptConfig}.
+ *
+ * @param config The configuration to inspect.
+ * @returns `true` for a derived prompt configuration.
+ * @since 1.3.0
+ */
+declare function isDerivedPromptConfig(config: unknown): config is DerivedPromptConfig<unknown, unknown>;
+/**
+ * Derives a prompt configuration from one dependency source value.
+ *
+ * The resolver may return the configuration synchronously or
+ * asynchronously.  It runs only during the real completion phase, after
+ * the named source has published its value—whether that value came from
+ * the command line, a source binding, or another prompt.
+ *
+ * @typeParam D The dependency source type.
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @param source The dependency source the resolver reads.
+ * @param resolver Produces the adapter configuration from the source
+ *                 value.
+ * @param options Optional declared default and runtime condition.
+ * @returns A derived configuration accepted by `prompt()` wrappers.
+ * @throws {TypeError} If `source` is not a dependency source.
+ * @since 1.3.0
+ */
+declare function derivePromptConfig<D extends AnyDependencySource, TConfig, const TOtherwise = never>(source: D, resolver: (value: DependencyValue<D>, context: DerivePromptConfigContext) => TConfig | Promise<TConfig>, options?: DerivePromptConfigOptions<DependencyValue<D>, TOtherwise>): DerivedPromptConfig<TConfig, TOtherwise>;
+/**
+ * Derives a prompt configuration from multiple dependency source values.
+ *
+ * The resolver receives the values as a tuple matching the declaration
+ * order of `sources`.  Evaluation order among prompts follows the
+ * dependency graph, not surrounding object or tuple field order.
+ *
+ * @typeParam Deps Tuple of dependency sources the resolver reads.
+ * @typeParam TConfig Adapter configuration produced by the resolver.
+ * @typeParam TOtherwise Value type returned when `when` skips the prompt.
+ * @param sources The dependency sources, at least one.
+ * @param resolver Produces the adapter configuration from the source
+ *                 values.
+ * @param options Optional declared defaults and runtime condition.
+ * @returns A derived configuration accepted by `prompt()` wrappers.
+ * @throws {TypeError} If `sources` is empty or contains a value that is
+ *         not a dependency source.
+ * @since 1.3.0
+ */
+declare function derivePromptConfig<const Deps extends readonly [AnyDependencySource, ...AnyDependencySource[]], TConfig, const TOtherwise = never>(sources: Deps, resolver: (values: DependencyValues<Deps>, context: DerivePromptConfigsContext<Deps>) => TConfig | Promise<TConfig>, options?: DerivePromptConfigsOptions<DependencyValues<Deps>, TOtherwise>): DerivedPromptConfig<TConfig, TOtherwise>;
+/**
+ * Prompt configuration accepted by a generated `prompt()` wrapper: either
+ * a static adapter configuration (optionally with a runtime condition) or
+ * a configuration derived from dependency sources via
+ * {@link derivePromptConfig}.
+ *
+ * @typeParam TConfig Prompt configuration accepted by the adapter.
+ * @typeParam TValue Value type produced by the wrapped parser.
+ * @since 1.3.0
+ */
+type PromptConfigInput<TConfig, TValue> = (TConfig & PromptCondition<TValue>) | DerivedPromptConfig<TConfig, NoInfer<TValue>>;
 /**
  * Creates a `prompt()` parser wrapper for a prompt library adapter.
  *
@@ -68,9 +238,10 @@ interface PromptAdapter<TConfig> {
  * @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.
+ *          parser.  The configuration may be a static `TConfig` or a
+ *          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
  * @since 1.2.0
  */
-declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: TConfig & PromptCondition<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>) => FluentParser<"async", TValue, TState>;
 //#endregion
-export { PromptAdapter, PromptCondition, createPromptAdapter };
+export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/dist/index.js

@@ -1,8 +1,115 @@
 import { getAnnotations } from "@optique/core/annotations";
+import { getDependencySourceInfo } from "@optique/core/dependency";
+import { message, values } from "@optique/core/message";
 import { defineTraits, delegateSuggestNodes, getTraits, inheritAnnotations, injectAnnotations, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView } from "@optique/core/extension";
 import { fluent } from "@optique/core/fluent";
 
 //#region src/index.ts
+const derivedPromptConfigMarker = Symbol.for("@optique/prompt/derivedPromptConfig");
+/**
+* Checks whether a prompt configuration was created by
+* {@link derivePromptConfig}.
+*
+* @param config The configuration to inspect.
+* @returns `true` for a derived prompt configuration.
+* @since 1.3.0
+*/
+function isDerivedPromptConfig(config) {
+	return config != null && typeof config === "object" && derivedPromptConfigMarker in config && config[derivedPromptConfigMarker] === true;
+}
+function derivePromptConfig(source, resolver, options) {
+	const isTuple = Array.isArray(source);
+	const dependencies = isTuple ? source : [source];
+	if (dependencies.length === 0) throw new TypeError("derivePromptConfig() requires at least one dependency source.");
+	const infos = dependencies.map(getDependencySourceInfo);
+	const singleDefault = options?.defaultValue;
+	const defaultValues = isTuple ? options?.defaultValues : singleDefault == null ? void 0 : () => [singleDefault()];
+	const resolve = isTuple ? (values$1, usedDefaults) => resolver(values$1, { usedDefaults }) : (values$1, usedDefaults) => resolver(values$1[0], { usedDefault: usedDefaults[0] });
+	return {
+		[derivedPromptConfigMarker]: true,
+		dependencies,
+		dependencyIds: infos.map((info) => info.sourceId),
+		dependencyLabels: infos.map((info, index) => info.metavar ?? `dependency #${index + 1}`),
+		resolve,
+		...defaultValues == null ? {} : { defaultValues },
+		...options?.when == null ? {} : {
+			when: options.when,
+			otherwise: options.otherwise
+		}
+	};
+}
+function describeThrown(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Resolves a derived prompt configuration against the dependency runtime.
+*
+* A failed upstream source fails the resolution transitively—the resolver
+* and the adapter never run.  A missing source uses the configuration's
+* declared default, or fails when none is declared.  Resolver exceptions
+* (synchronous throws and rejections alike) become prompt failures so
+* the scheduler treats them like a cancelled prompt.
+*/
+async function resolveDerivedPromptConfig(config, exec, ownSourceId, ownLabel) {
+	const runtime = exec?.dependencyRuntime;
+	const ids = config.dependencyIds;
+	if (runtime != null) {
+		const failedIndex = ids.findIndex((id) => runtime.isSourceFailed(id));
+		if (failedIndex >= 0) {
+			runtime.propagateSourceFailure(ids, ownLabel ?? "prompt", ownSourceId);
+			const base = message`Cannot resolve prompt configuration: dependency ${config.dependencyLabels[failedIndex]} failed.`;
+			const chain = ownSourceId == null ? runtime.getSourceFailureChain(ids[failedIndex]) : void 0;
+			return {
+				ok: false,
+				error: chain == null || chain.length < 2 ? base : message`${base} Dependency chain: ${chain.join(" -> ")}.`
+			};
+		}
+	}
+	const missing = [];
+	const values$1 = ids.map((id, index) => {
+		if (runtime?.hasSource(id) === true) return runtime.getSource(id);
+		missing.push(index);
+		return void 0;
+	});
+	const usedDefaults = ids.map(() => false);
+	if (missing.length > 0) {
+		if (config.defaultValues == null) {
+			const missingLabels = values(missing.map((index) => config.dependencyLabels[index]));
+			return {
+				ok: false,
+				error: missing.length > 1 ? message`Cannot resolve prompt configuration: dependencies ${missingLabels} are not available and no default values are declared.` : message`Cannot resolve prompt configuration: dependency ${missingLabels} is not available and no default value is declared.`
+			};
+		}
+		let defaults;
+		try {
+			defaults = config.defaultValues();
+		} catch (error) {
+			return {
+				ok: false,
+				error: message`Prompt configuration default evaluation failed: ${describeThrown(error)}`
+			};
+		}
+		if (defaults.length !== ids.length) return {
+			ok: false,
+			error: message`Prompt configuration declared ${String(defaults.length)} default values for ${String(ids.length)} dependencies.`
+		};
+		for (const index of missing) {
+			values$1[index] = defaults[index];
+			usedDefaults[index] = true;
+		}
+	}
+	try {
+		return {
+			ok: true,
+			config: await config.resolve(values$1, usedDefaults)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: message`Prompt configuration resolution failed: ${describeThrown(error)}`
+		};
+	}
+}
 function shouldDeferPrompt(parser, state, exec) {
 	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state, exec) === true;
 }
@@ -37,6 +144,7 @@ function hasSourceBindingMarker(state) {
 	return state != null && typeof state === "object" && "hasCliValue" in state && Object.getOwnPropertySymbols(state).length > 0;
 }
 function readDefaultValue(adapter, config) {
+	if (isDerivedPromptConfig(config)) return void 0;
 	if (adapter.getDefaultValue != null) return adapter.getDefaultValue(config);
 	if (config != null && typeof config === "object" && "default" in config) return config.default;
 	return void 0;
@@ -59,7 +167,8 @@ 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.
+*          parser.  The configuration may be a static `TConfig` or a
+*          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
 * @since 1.2.0
 */
 function createPromptAdapter(adapter) {
@@ -108,12 +217,19 @@ function createPromptAdapter(adapter) {
 			if (cliStateIsInjectedAnnotationWrapper && requiresSourceBindingForAnnotationWrapper) return hasNestedSourceBinding;
 			return shouldAttemptInnerCompletion(cliState, state) || hasNestedSourceBinding;
 		}
-		async function executePrompt() {
+		async function executePrompt(exec) {
 			if (config.when != null && !await config.when()) return {
 				success: true,
 				value: config.otherwise
 			};
-			return adapter.execute(config);
+			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);
 		}
 		const parserInheritsAnnotations = getTraits(parser).inheritsAnnotations === true;
 		const promptedParser = {
@@ -224,13 +340,15 @@ function createPromptAdapter(adapter) {
 							return Promise.resolve(cached);
 						}
 						if (session.policy === "demand-only" && !session.demanded.has(sourceId)) return Promise.resolve(deferredPromptResult(readPlaceholder()));
-						return executePrompt().then((result) => {
+						if (session.policy === "demand-only" && isDerivedPromptConfig(config) && config.dependencyIds.some((id) => exec?.dependencyRuntime?.hasSource(id) !== true && exec?.dependencyRuntime?.isSourceFailed(id) !== true)) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+						return executePrompt(exec).then((result) => {
 							session.results.set(cacheKey, result);
 							session.effectfulSources.add(sourceId);
 							return result;
 						});
 					}
-					return executePrompt();
+					if (session?.policy === "demand-only" && isDerivedPromptConfig(config)) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+					return executePrompt(exec);
 				};
 				const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
 				const decideFromParse = (parseResult) => {
@@ -314,8 +432,12 @@ function createPromptAdapter(adapter) {
 			},
 			completeSource: source.preservesSourceValue === false ? void 0 : (state, exec) => promptedParser.complete(state, exec)
 		}));
-		if (dependencyMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
-			value: dependencyMetadata,
+		const composedMetadata = isDerivedPromptConfig(config) ? {
+			...dependencyMetadata ?? {},
+			completion: { dependencyIds: config.dependencyIds }
+		} : dependencyMetadata;
+		if (composedMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
+			value: composedMetadata,
 			configurable: true,
 			enumerable: false
 		});
@@ -324,4 +446,4 @@ function createPromptAdapter(adapter) {
 }
 
 //#endregion
-export { createPromptAdapter };
+export { createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/package.json

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