@optique/core 1.3.0-dev.2379 → 1.3.0-dev.2381

package/dist/dependency-metadata.d.cts

@@ -1,5 +1,5 @@
 import { ValueParser, ValueParserResult } from "./valueparser.cjs";
-import { Mode, Suggestion } from "./internal/parser.cjs";
+import { ExecutionContext, Mode, Suggestion } from "./internal/parser.cjs";
 
 //#region src/dependency-metadata.d.ts
 
@@ -37,6 +37,25 @@ interface DependencySourceCapability {
    * phase of the dependency runtime.
    */
   readonly getMissingSourceValue?: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+  /**
+   * Runs the parser's effectful completion (e.g., an interactive prompt)
+   * to obtain the source value when it is not extractable from state.
+   *
+   * Invoked only during real completion (never probes, help, or suggest),
+   * serially in declaration order, at most once per parse operation—the
+   * result is cached in the run-scoped effectful completion session.  Only
+   * honored in asynchronous completion lanes; synchronous completion
+   * ignores this hook, in which case the owning parser still completes
+   * normally in the construct's final completion phase without early
+   * registration.
+   *
+   * May resolve to `undefined` when the state offers nothing to complete.
+   * A result marked `deferred` is treated the same way: it is skipped and
+   * never registered.
+   *
+   * @since 1.3.0
+   */
+  readonly completeSource?: (state: unknown, exec?: ExecutionContext) => Promise<ValueParserResult<unknown> | undefined>;
   /**
    * Whether the parser's output value is the actual dependency source value.
    * `false` when a transform like `map()` has been applied.

package/dist/dependency-metadata.d.ts

@@ -1,5 +1,5 @@
 import { ValueParser, ValueParserResult } from "./valueparser.js";
-import { Mode, Suggestion } from "./internal/parser.js";
+import { ExecutionContext, Mode, Suggestion } from "./internal/parser.js";
 
 //#region src/dependency-metadata.d.ts
 
@@ -37,6 +37,25 @@ interface DependencySourceCapability {
    * phase of the dependency runtime.
    */
   readonly getMissingSourceValue?: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+  /**
+   * Runs the parser's effectful completion (e.g., an interactive prompt)
+   * to obtain the source value when it is not extractable from state.
+   *
+   * Invoked only during real completion (never probes, help, or suggest),
+   * serially in declaration order, at most once per parse operation—the
+   * result is cached in the run-scoped effectful completion session.  Only
+   * honored in asynchronous completion lanes; synchronous completion
+   * ignores this hook, in which case the owning parser still completes
+   * normally in the construct's final completion phase without early
+   * registration.
+   *
+   * May resolve to `undefined` when the state offers nothing to complete.
+   * A result marked `deferred` is treated the same way: it is skipped and
+   * never registered.
+   *
+   * @since 1.3.0
+   */
+  readonly completeSource?: (state: unknown, exec?: ExecutionContext) => Promise<ValueParserResult<unknown> | undefined>;
   /**
    * Whether the parser's output value is the actual dependency source value.
    * `false` when a transform like `map()` has been applied.

package/dist/dependency-metadata.js

@@ -74,6 +74,16 @@ function unwrapArrayThenExtract(innerExtract) {
 	};
 }
 /**
+* Wraps an inner `completeSource` to unwrap `[innerState]` first, mirroring
+* `unwrapArrayThenExtract` for the effectful completion operation.
+*/
+function unwrapArrayThenComplete(innerComplete) {
+	return (state, exec) => {
+		if (Array.isArray(state) && state.length === 1) return innerComplete(state[0], exec);
+		return innerComplete(state, exec);
+	};
+}
+/**
 * Composes dependency metadata through a modifier wrapper.
 *
 * - `"optional"`: composes `extractSourceValue` with array unwrapping.
@@ -99,7 +109,8 @@ function composeDependencyMetadata(inner, wrapperKind, options) {
 				...inner,
 				source: {
 					...inner.source,
-					extractSourceValue: unwrapArrayThenExtract(inner.source.extractSourceValue)
+					extractSourceValue: unwrapArrayThenExtract(inner.source.extractSourceValue),
+					...inner.source.completeSource != null && { completeSource: unwrapArrayThenComplete(inner.source.completeSource) }
 				}
 			};
 			return inner;
@@ -112,6 +123,7 @@ function composeDependencyMetadata(inner, wrapperKind, options) {
 				source: {
 					...inner.source,
 					...wrappedExtract != null && { extractSourceValue: wrappedExtract },
+					...inner.source.completeSource != null && { completeSource: unwrapArrayThenComplete(inner.source.completeSource) },
 					...preservesSourceValue && options?.defaultValue != null && { getMissingSourceValue: options.defaultValue }
 				}
 			};

package/dist/dependency-runtime.cjs

@@ -478,6 +478,218 @@ function extractRawInputFromState(state) {
 	return void 0;
 }
 /**
+* Internal parser hook for constructs whose effectful scheduling nodes
+* cannot be derived from flattened field pairs alone.
+*
+* `merge()` installs it so a parent's scheduling expansion uses the same
+* child-indexed paths, declaration order, and duplicate-field exclusion
+* as the merge's own scheduling pass; `or()`/`longestMatch()` install it
+* to expose the committed branch; `command()` installs it to expose its
+* inner parser once the command has matched.  The returned node paths
+* must match the execution paths used when the same parsers complete, so
+* the run-scoped completion cache lines up.
+*
+* @internal
+* @since 1.3.0
+*/
+const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/effectfulSchedulingNodes");
+/**
+* Forwards effectful scheduling through a shape-preserving wrapper such
+* as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
+* wrapped parser—a selected exclusive or command branch, or an ordinary
+* construct with nested effectful sources—stays visible to a parent
+* construct's scheduling expansion.
+*
+* The installed hook simply re-exposes the inner parser as a node with
+* the wrapper's own state shape unwrapped (`adaptState`, e.g. the
+* `[innerState]` array used by `optional()`/`withDefault()`); the
+* expansion then applies its ordinary rules to the inner parser, whether
+* it carries its own hook, flattened field pairs, or source metadata.
+* Wrappers are path-transparent, so the node keeps the wrapper's path.
+*
+* @internal
+* @since 1.3.0
+*/
+function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
+	if (inner.dependencyMetadata?.source != null) return;
+	Object.defineProperty(wrapper, effectfulSchedulingNodesKey, {
+		value: ((state, parentPath) => [{
+			path: parentPath ?? [],
+			parser: inner,
+			state: adaptState == null ? state : adaptState(state)
+		}]),
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Collects the dependency source IDs demanded by consumers among the
+* given nodes and state subtree.
+*
+* A consumer demands its sources when it has raw input evidence: either a
+* trace entry recorded at its path during parsing, or a legacy
+* `DeferredParseState` embedded in the state subtree.  Consumers without
+* raw input never replay against real dependency values, so their sources
+* are not demanded.
+*
+* @param nodes The direct-child runtime nodes of the owning construct.
+* @param state The construct's state subtree (for legacy deferred states).
+* @param trace The input trace recorded during parsing.
+* @returns The set of demanded dependency source IDs.
+* @internal
+* @since 1.3.0
+*/
+function collectDemandedDependencyIds(nodes, state, trace) {
+	const demanded = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		const derived = node.parser.dependencyMetadata?.derived;
+		if (derived == null) continue;
+		const hasRawInput = trace?.get(node.path)?.rawInput != null || extractRawInputFromState(node.state) != null;
+		if (!hasRawInput) continue;
+		for (const id of derived.dependencyIds) demanded.add(id);
+	}
+	collectDeferredDemand(state, demanded, /* @__PURE__ */ new WeakSet());
+	return demanded;
+}
+function collectDeferredDemand(state, demanded, visited) {
+	if (state == null || typeof state !== "object") return;
+	if (visited.has(state)) return;
+	visited.add(state);
+	if (require_internal_dependency.isDeferredParseState(state)) {
+		const ids = state.dependencyIds != null && state.dependencyIds.length > 0 ? state.dependencyIds : [state.dependencyId];
+		for (const id of ids) demanded.add(id);
+		return;
+	}
+	for (const key of Reflect.ownKeys(state)) collectDeferredDemand(state[key], demanded, visited);
+}
+/**
+* Runs effectful source completions (e.g., interactive prompts) serially
+* in declaration order for source nodes whose value is not yet registered.
+*
+* This is the scheduling half of the `completeSource` capability contract:
+*
+* - Runs only during real completion (`exec.phase === "complete"`); probe
+*   and suggest phases return immediately without effects.
+* - Precedence is structural: a source whose value was registered before
+*   the pass begins (from CLI state, environment, configuration, or a
+*   default) or that has already failed is never completed effectfully.
+*   When several scheduled occurrences share one source, each occurrence
+*   still completes and re-registers, so the last occurrence wins—the
+*   same rule as repeated command-line source occurrences.
+* - Completion results that are `undefined` or marked `deferred` are
+*   treated as declined and neither registered nor cached.
+* - A successful result registers its value unless the value is
+*   `undefined`.  When the node is reusable (a direct child whose field
+*   value is the source value), the result is also returned for reuse by
+*   the owning construct so the node is not completed twice; otherwise the
+*   effectful parser's own run-scoped session cache prevents a second
+*   execution, so nodes that are not reusable are only scheduled when a
+*   session is present.  For a source behind a transform such as `map()`
+*   (`preservesSourceValue: false`), the `completeSource` contract still
+*   yields the pre-transform source value, so registration stays correct
+*   while the field's final value is produced separately.
+* - A failed result (e.g., a cancelled prompt) marks the source as failed
+*   and aborts immediately—later effectful completions do not run.
+*
+* When the run-scoped session policy is `"demand-only"` (the phase-two
+* seed pass), the demanded source IDs from
+* {@link collectDemandedDependencyIds} are added to the session before any
+* completion runs, letting effectful parsers defer when no phase-one
+* consumer demands their value.
+*
+* @param nodes The runtime nodes to schedule, in declaration order.
+* @param state The construct's state subtree (for demand detection).
+* @param runtime The dependency runtime context.
+* @param exec The execution context of the owning construct.
+* @param options Scheduling options.
+* @returns The scheduling result: completed nodes for reuse, or the first
+*   failure.
+* @internal
+* @since 1.3.0
+*/
+async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, options) {
+	const empty = {
+		success: true,
+		completed: []
+	};
+	if (exec == null || exec.phase !== "complete") return empty;
+	const session = exec.effectfulCompletionSession;
+	if (session?.policy === "demand-only") {
+		const demandNodes = options?.demandNodes ?? nodes;
+		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
+		for (const id of demanded) session.demanded.add(id);
+	}
+	if (session != null) {
+		for (const result of session.results.values()) if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+	}
+	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
+	if (schedulable.length === 0) return empty;
+	const preexisting = /* @__PURE__ */ new Set();
+	for (const node of schedulable) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null && runtime.hasSource(source.sourceId) && session?.effectfulSources.has(source.sourceId) !== true) preexisting.add(source.sourceId);
+	}
+	const completed = [];
+	for (const node of schedulable) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source?.completeSource == null) continue;
+		const pathKey = serializeSchedulingPath(node.path);
+		const priorResult = session?.completedByPath.get(pathKey);
+		if (priorResult != null) {
+			if (source.preservesSourceValue && (options?.isReusable?.(node) ?? true)) completed.push({
+				key: node.path[node.path.length - 1],
+				result: priorResult
+			});
+			continue;
+		}
+		if (preexisting.has(source.sourceId)) continue;
+		const reusable = source.preservesSourceValue && (options?.isReusable?.(node) ?? true);
+		if (!reusable && session == null) continue;
+		const childExec = {
+			...exec,
+			path: node.path
+		};
+		const result = await source.completeSource(node.state, childExec);
+		if (result == null) continue;
+		if (!result.success) {
+			runtime.markSourceFailed(source.sourceId);
+			return {
+				success: false,
+				error: result.error
+			};
+		}
+		if (result.deferred === true) continue;
+		session?.completedByPath.set(pathKey, result);
+		if (reusable) completed.push({
+			key: node.path[node.path.length - 1],
+			result
+		});
+		if (result.value !== void 0) runtime.registerSource(source.sourceId, result.value);
+	}
+	return {
+		success: true,
+		completed
+	};
+}
+/**
+* Serializes a scheduling node path into a stable string key, using
+* length-prefixed segments so no separator escaping is needed.
+*/
+function serializeSchedulingPath(path) {
+	return path.map((segment) => {
+		if (typeof segment === "symbol") {
+			const key = stableSymbolKey(segment);
+			return `y${key.length}:${key}`;
+		}
+		const tag = typeof segment === "number" ? "n" : "s";
+		const text = String(segment);
+		return `${tag}${text.length}:${text}`;
+	}).join("");
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -719,12 +931,16 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 //#endregion
 exports.buildRuntimeNodesFromArray = buildRuntimeNodesFromArray;
 exports.buildRuntimeNodesFromPairs = buildRuntimeNodesFromPairs;
+exports.collectDemandedDependencyIds = collectDemandedDependencyIds;
 exports.collectExplicitSourceValues = collectExplicitSourceValues;
 exports.collectExplicitSourceValuesAsync = collectExplicitSourceValuesAsync;
 exports.collectSourcesFromState = collectSourcesFromState;
+exports.completeEffectfulSourcesAsync = completeEffectfulSourcesAsync;
 exports.createDependencyFingerprint = createDependencyFingerprint;
 exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
 exports.createReplayKey = createReplayKey;
+exports.defineForwardedEffectfulSchedulingNodes = defineForwardedEffectfulSchedulingNodes;
+exports.effectfulSchedulingNodesKey = effectfulSchedulingNodesKey;
 exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;

package/dist/dependency-runtime.d.cts

@@ -1,6 +1,9 @@
+import { Message } from "./message.cjs";
 import { DependencyRegistryLike } from "./registry-types.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { ParserDependencyMetadata } from "./dependency-metadata.cjs";
+import { InputTrace } from "./input-trace.cjs";
+import { ExecutionContext } from "./internal/parser.cjs";
 
 //#region src/dependency-runtime.d.ts
 
@@ -255,6 +258,164 @@ declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, r
  * @since 1.0.0
  */
 declare function extractRawInputFromState(state: unknown): string | undefined;
+/**
+ * Internal parser hook for constructs whose effectful scheduling nodes
+ * cannot be derived from flattened field pairs alone.
+ *
+ * `merge()` installs it so a parent's scheduling expansion uses the same
+ * child-indexed paths, declaration order, and duplicate-field exclusion
+ * as the merge's own scheduling pass; `or()`/`longestMatch()` install it
+ * to expose the committed branch; `command()` installs it to expose its
+ * inner parser once the command has matched.  The returned node paths
+ * must match the execution paths used when the same parsers complete, so
+ * the run-scoped completion cache lines up.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const effectfulSchedulingNodesKey: unique symbol;
+/**
+ * The shape of the {@link effectfulSchedulingNodesKey} hook.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+/**
+ * Forwards effectful scheduling through a shape-preserving wrapper such
+ * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
+ * wrapped parser—a selected exclusive or command branch, or an ordinary
+ * construct with nested effectful sources—stays visible to a parent
+ * construct's scheduling expansion.
+ *
+ * The installed hook simply re-exposes the inner parser as a node with
+ * the wrapper's own state shape unwrapped (`adaptState`, e.g. the
+ * `[innerState]` array used by `optional()`/`withDefault()`); the
+ * expansion then applies its ordinary rules to the inner parser, whether
+ * it carries its own hook, flattened field pairs, or source metadata.
+ * Wrappers are path-transparent, so the node keeps the wrapper's path.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function defineForwardedEffectfulSchedulingNodes(wrapper: object, inner: {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+}, adaptState?: (state: unknown) => unknown): void;
+/**
+ * A completed effectful source result to be reused by the owning
+ * construct's final completion phase, keyed by the node's last path
+ * segment (its field key or tuple index).
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface EffectfulSourceCompletion {
+  /** The node's field key or index (its last path segment). */
+  readonly key: PropertyKey;
+  /** The effectful completion result. */
+  readonly result: ValueParserResult<unknown>;
+}
+/**
+ * The result of scheduling effectful source completions.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+type EffectfulSourceCompletionResult = {
+  readonly success: true;
+  readonly completed: readonly EffectfulSourceCompletion[];
+} | {
+  readonly success: false;
+  readonly error: Message;
+};
+/**
+ * Collects the dependency source IDs demanded by consumers among the
+ * given nodes and state subtree.
+ *
+ * A consumer demands its sources when it has raw input evidence: either a
+ * trace entry recorded at its path during parsing, or a legacy
+ * `DeferredParseState` embedded in the state subtree.  Consumers without
+ * raw input never replay against real dependency values, so their sources
+ * are not demanded.
+ *
+ * @param nodes The direct-child runtime nodes of the owning construct.
+ * @param state The construct's state subtree (for legacy deferred states).
+ * @param trace The input trace recorded during parsing.
+ * @returns The set of demanded dependency source IDs.
+ * @internal
+ * @since 1.3.0
+ */
+declare function collectDemandedDependencyIds(nodes: readonly RuntimeNode[], state: unknown, trace: InputTrace | undefined): ReadonlySet<symbol>;
+/**
+ * Options for {@link completeEffectfulSourcesAsync}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface CompleteEffectfulSourcesOptions {
+  /**
+   * Nodes used for demand detection instead of the scheduled nodes.
+   * Constructs whose parse-time trace paths differ from their scheduling
+   * node paths (e.g., `merge()`, which records child-indexed paths but
+   * schedules flattened field nodes) pass path-corrected nodes here.
+   */
+  readonly demandNodes?: readonly RuntimeNode[];
+  /**
+   * Whether a node's completion result may be cached by the owning
+   * construct for reuse in its final completion phase.  Defaults to
+   * treating every node as reusable.  Non-reusable completions (nodes
+   * expanded from nested children, or sources whose field value differs
+   * from the source value) rely on the run-scoped session cache to avoid
+   * running twice, and are skipped when no session is available.
+   */
+  readonly isReusable?: (node: RuntimeNode) => boolean;
+}
+/**
+ * Runs effectful source completions (e.g., interactive prompts) serially
+ * in declaration order for source nodes whose value is not yet registered.
+ *
+ * This is the scheduling half of the `completeSource` capability contract:
+ *
+ * - Runs only during real completion (`exec.phase === "complete"`); probe
+ *   and suggest phases return immediately without effects.
+ * - Precedence is structural: a source whose value was registered before
+ *   the pass begins (from CLI state, environment, configuration, or a
+ *   default) or that has already failed is never completed effectfully.
+ *   When several scheduled occurrences share one source, each occurrence
+ *   still completes and re-registers, so the last occurrence wins—the
+ *   same rule as repeated command-line source occurrences.
+ * - Completion results that are `undefined` or marked `deferred` are
+ *   treated as declined and neither registered nor cached.
+ * - A successful result registers its value unless the value is
+ *   `undefined`.  When the node is reusable (a direct child whose field
+ *   value is the source value), the result is also returned for reuse by
+ *   the owning construct so the node is not completed twice; otherwise the
+ *   effectful parser's own run-scoped session cache prevents a second
+ *   execution, so nodes that are not reusable are only scheduled when a
+ *   session is present.  For a source behind a transform such as `map()`
+ *   (`preservesSourceValue: false`), the `completeSource` contract still
+ *   yields the pre-transform source value, so registration stays correct
+ *   while the field's final value is produced separately.
+ * - A failed result (e.g., a cancelled prompt) marks the source as failed
+ *   and aborts immediately—later effectful completions do not run.
+ *
+ * When the run-scoped session policy is `"demand-only"` (the phase-two
+ * seed pass), the demanded source IDs from
+ * {@link collectDemandedDependencyIds} are added to the session before any
+ * completion runs, letting effectful parsers defer when no phase-one
+ * consumer demands their value.
+ *
+ * @param nodes The runtime nodes to schedule, in declaration order.
+ * @param state The construct's state subtree (for demand detection).
+ * @param runtime The dependency runtime context.
+ * @param exec The execution context of the owning construct.
+ * @param options Scheduling options.
+ * @returns The scheduling result: completed nodes for reuse, or the first
+ *   failure.
+ * @internal
+ * @since 1.3.0
+ */
+declare function completeEffectfulSourcesAsync(nodes: readonly RuntimeNode[], state: unknown, runtime: DependencyRuntimeContext, exec: ExecutionContext | undefined, options?: CompleteEffectfulSourcesOptions): Promise<EffectfulSourceCompletionResult>;
 /**
  * Recursively collects dependency source values from {@link DependencySourceState}
  * objects found in the state tree and registers them in the runtime.
@@ -334,4 +495,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };