@optique/env 1.0.0-dev.921 → 1.0.1

package/dist/index.cjs

@@ -22,37 +22,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_extension = __toESM(require("@optique/core/extension"));
 const __optique_core_message = __toESM(require("@optique/core/message"));
-const __optique_core_mode_dispatch = __toESM(require("@optique/core/mode-dispatch"));
 const __optique_core_valueparser = __toESM(require("@optique/core/valueparser"));
 
 //#region src/index.ts
-const deferPromptUntilConfigResolvesKey = Symbol.for("@optique/config/deferPromptUntilResolved");
-const activeEnvSourceRegistry = /* @__PURE__ */ new Map();
-/**
-* Sets active environment source data for a context.
-*
-* @internal
-*/
-function setActiveEnvSource(contextId, sourceData) {
-	activeEnvSourceRegistry.set(contextId, sourceData);
-}
-/**
-* Gets active environment source data for a context.
-*
-* @internal
-*/
-function getActiveEnvSource(contextId) {
-	return activeEnvSourceRegistry.get(contextId);
-}
-/**
-* Clears active environment source data for a context.
-*
-* @internal
-*/
-function clearActiveEnvSource(contextId) {
-	activeEnvSourceRegistry.delete(contextId);
-}
 function defaultEnvSource(key) {
 	const denoGlobal = globalThis.Deno;
 	if (typeof denoGlobal?.env?.get === "function") return denoGlobal.env.get(key);
@@ -62,30 +36,39 @@ function defaultEnvSource(key) {
 /**
 * Creates an environment context for use with Optique runners.
 *
+* When calling `context.getAnnotations()` manually, pass the returned
+* annotations to low-level APIs such as `parse()`, `parseAsync()`,
+* `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
+* contexts are single-pass, `getAnnotations()` can still be called without
+* a phase request. Calling it by itself does not affect later parses.
+*
 * @param options Environment context options.
 * @returns A context that provides environment source annotations.
+* @throws {TypeError} If `prefix` is not a string.
+* @throws {TypeError} If `source` is not a function.
 * @since 1.0.0
 */
 function createEnvContext(options = {}) {
 	const contextId = Symbol(`@optique/env context:${Math.random()}`);
-	const source = options.source ?? defaultEnvSource;
-	const prefix = options.prefix ?? "";
+	const rawSource = options.source;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${rawSource === null ? "null" : Array.isArray(rawSource) ? "array" : typeof rawSource}.`);
+	const source = rawSource ?? defaultEnvSource;
+	const rawPrefix = options.prefix;
+	if (rawPrefix !== void 0 && typeof rawPrefix !== "string") throw new TypeError(`Expected prefix to be a string, but got: ${rawPrefix === null ? "null" : Array.isArray(rawPrefix) ? "array" : typeof rawPrefix}.`);
+	const prefix = rawPrefix ?? "";
 	return {
 		id: contextId,
 		prefix,
 		source,
-		mode: "static",
+		phase: "single-pass",
 		getAnnotations() {
 			const sourceData = {
 				prefix,
 				source
 			};
-			setActiveEnvSource(contextId, sourceData);
 			return { [contextId]: sourceData };
 		},
-		[Symbol.dispose]() {
-			clearActiveEnvSource(contextId);
-		}
+		[Symbol.dispose]() {}
 	};
 }
 /**
@@ -101,20 +84,28 @@ function createEnvContext(options = {}) {
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
+* @throws {TypeError} If `key` is not a string or `parser` is not a valid
+*                    {@link ValueParser}.
 * @throws {Error} If the inner parser throws while parsing or completing a
 *                 value, if the environment source throws while reading a
-*                 variable, or if the environment value parser throws while
-*                 parsing the environment variable value.
+*                 variable, if the environment value parser throws while
+*                 parsing the environment variable value, or if the inner
+*                 parser's {@link Parser.validateValue} hook throws while
+*                 re-validating a fallback value (environment variable value
+*                 or configured `default`) — the hook can run even when no
+*                 CLI tokens are parsed (see issue #414).
 * @since 1.0.0
 */
 function bindEnv(parser, options) {
+	if (typeof options.key !== "string") throw new TypeError(`Expected key to be a string, but got: ${options.key === null ? "null" : Array.isArray(options.key) ? "array" : typeof options.key}.`);
+	if (!(0, __optique_core_valueparser.isValueParser)(options.parser)) throw new TypeError(`Expected parser to be a ValueParser, but got: ${options.parser === null ? "null" : Array.isArray(options.parser) ? "array" : typeof options.parser}.`);
 	const envBindStateKey = Symbol("@optique/env/bindState");
 	function isEnvBindState(value) {
 		return value != null && typeof value === "object" && envBindStateKey in value;
 	}
-	const deferPromptUntilConfigResolves = Reflect.get(parser, deferPromptUntilConfigResolvesKey);
-	return {
-		$mode: parser.$mode,
+	const deferPromptUntilConfigResolves = parser.shouldDeferCompletion;
+	const boundParser = {
+		mode: parser.mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
@@ -122,7 +113,13 @@ function bindEnv(parser, options) {
 			type: "optional",
 			terms: parser.usage
 		}] : parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = isEnvBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+			return (0, __optique_core_extension.delegateSuggestNodes)(parser, boundParser, state, path, innerState);
+		},
 		parse: (context) => {
 			const annotations = (0, __optique_core_annotations.getAnnotations)(context.state);
 			const innerState = isEnvBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
@@ -133,14 +130,14 @@ function bindEnv(parser, options) {
 			const processResult = (result) => {
 				if (result.success) {
 					const cliConsumed = result.consumed.length > 0;
-					const nextState$1 = {
+					const nextState$1 = (0, __optique_core_extension.injectAnnotations)({
 						[envBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result.next.state,
-						...annotations && { [__optique_core_annotations.annotationKey]: annotations }
-					};
+						cliState: result.next.state
+					}, annotations);
 					return {
 						success: true,
+						...result.provisional ? { provisional: true } : {},
 						next: {
 							...result.next,
 							state: nextState$1
@@ -149,11 +146,10 @@ function bindEnv(parser, options) {
 					};
 				}
 				if (result.consumed > 0) return result;
-				const nextState = {
+				const nextState = (0, __optique_core_extension.injectAnnotations)({
 					[envBindStateKey]: true,
-					hasCliValue: false,
-					...annotations && { [__optique_core_annotations.annotationKey]: annotations }
-				};
+					hasCliValue: false
+				}, annotations);
 				return {
 					success: true,
 					next: {
@@ -163,42 +159,204 @@ function bindEnv(parser, options) {
 					consumed: []
 				};
 			};
-			return (0, __optique_core_mode_dispatch.mapModeValue)(parser.$mode, parser.parse(innerContext), processResult);
+			return (0, __optique_core_extension.mapModeValue)(parser.mode, parser.parse(innerContext), processResult);
 		},
-		complete: (state) => {
-			if (isEnvBindState(state) && state.hasCliValue) return parser.complete(state.cliState);
-			return getEnvOrDefault(state, options, parser.$mode, parser, isEnvBindState(state) ? state.cliState : void 0);
+		complete: (state, exec) => {
+			if (isEnvBindState(state) && state.hasCliValue) return parser.complete(state.cliState, exec);
+			return getEnvOrDefault(state, options, parser.mode, parser, isEnvBindState(state) ? state.cliState : (0, __optique_core_extension.isInjectedAnnotationState)(state) ? void 0 : state, exec);
 		},
 		suggest: parser.suggest,
-		...typeof deferPromptUntilConfigResolves === "function" ? { [deferPromptUntilConfigResolvesKey]: (state) => deferPromptUntilConfigResolves(state) } : {},
+		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: (state, exec) => deferPromptUntilConfigResolves.call(parser, state, exec) } : {},
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	(0, __optique_core_extension.defineTraits)(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(boundParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = (0, __optique_core_extension.mapSourceMetadata)(parser, (sourceMetadata) => ({
+		...sourceMetadata,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return parser.validateValue(options.default);
+			return {
+				success: true,
+				value: options.default
+			};
+		} : void 0,
+		extractSourceValue: (state) => {
+			if (!isEnvBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
+				return sourceMetadata.extractSourceValue(state);
+			}
+			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
+			const innerState = state.cliState ?? state;
+			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(innerState);
+			return getEnvSourceValue(state, options, innerState, sourceMetadata.extractSourceValue, parser);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
+	return boundParser;
 }
-function getEnvOrDefault(state, options, mode, innerParser, innerState) {
+/**
+* Resolves a `bindEnv()` fallback value with env > default > inner
+* `complete()` priority, running each candidate through the inner
+* parser's `validateValue()` hook when available so the inner CLI
+* parser's constraints are enforced on fallback values (see issue
+* #414).
+*
+* @param state The wrapper state, which may carry env annotations.
+* @param options The binding options with lookup and default settings.
+* @param mode The parser mode (`"sync"` or `"async"`), used to
+*             dispatch env parsing and fallback validation.
+* @param innerParser Optional wrapped parser.  When present, its
+*                    `validateValue()` hook is used to re-validate
+*                    fallback values and its `complete()` is
+*                    delegated to as the last fallback.
+* @param innerState Optional unwrapped inner state to pass through to
+*                   `innerParser.complete()`.
+* @param exec Optional execution context forwarded to
+*             `innerParser.complete()`.
+* @returns The resolved value as a mode-dependent result.
+* @throws {Error} Propagates errors thrown by the env source callback
+*                 (`sourceData.source(fullKey)`) while reading the
+*                 environment variable.
+* @throws {Error} Propagates errors thrown by
+*                 `options.parser.parse(rawValue)` (sync or async)
+*                 while parsing the raw env string into `TValue`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while re-validating
+*                 a successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's
+*                 constraints.
+* @throws {Error} Propagates errors thrown by `innerParser.complete()`
+*                 when falling through to the inner parser (e.g.,
+*                 `bindEnv(bindConfig(...))` with neither env nor
+*                 default set).
+*/
+function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
-	const sourceData = annotations?.[options.context.id] ?? getActiveEnvSource(options.context.id);
+	const sourceData = annotations?.[options.context.id];
 	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
 	const rawValue = sourceData?.source(fullKey);
+	const validateSync = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
+	const validateAsync = async (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return await innerParser.validateValue(parsed.value);
+	};
 	if (rawValue !== void 0) {
-		const parsed = options.parser.parse(rawValue);
-		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, parsed);
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return (0, __optique_core_extension.wrapForMode)(mode, {
+				success: false,
+				error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} must be a string, but got: ${type}.`
+			});
+		}
+		return (0, __optique_core_extension.dispatchByMode)(mode, () => {
+			const parsed = options.parser.parse(rawValue);
+			return validateSync(parsed);
+		}, async () => {
+			const parsed = await options.parser.parse(rawValue);
+			return await validateAsync(parsed);
+		});
 	}
-	if (options.default !== void 0) return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
+	if (options.default !== void 0) return (0, __optique_core_extension.dispatchByMode)(mode, () => validateSync({
 		success: true,
 		value: options.default
-	});
+	}), () => validateAsync({
+		success: true,
+		value: options.default
+	}));
 	if (innerParser != null) {
-		const completeState = innerState ?? innerParser.initialState;
-		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, innerParser.complete(completeState));
+		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && (0, __optique_core_extension.getTraits)(innerParser).inheritsAnnotations === true ? (0, __optique_core_extension.injectAnnotations)(innerParser.initialState, annotations) : innerParser.initialState);
+		return (0, __optique_core_extension.wrapForMode)(mode, innerParser.complete(completeState, exec));
 	}
-	return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
+	return (0, __optique_core_extension.wrapForMode)(mode, {
 		success: false,
 		error: __optique_core_message.message`Missing required environment variable: ${(0, __optique_core_message.envVar)(fullKey)}`
 	});
 }
+/**
+* Resolves an env-backed dependency source with env and default fallbacks.
+*
+* This first checks annotations for the bound variable. If no env-backed value
+* is available, it falls back to `options.default` and finally delegates to
+* the wrapped parser's source extractor.
+*
+* When `innerParser` exposes a `validateValue` hook, env-sourced values
+* and the configured default are re-validated against the inner parser's
+* CLI constraints (see issue #414).  This is only called from the
+* `preservesSourceValue: true` branch in {@link bindEnv}, so the source
+* value type is guaranteed to equal `TValue`.
+*
+* @param state The wrapper state, which may carry env annotations.
+* @param options The binding options with lookup and default settings.
+* @param innerState The unwrapped inner state for delegated extraction.
+* @param extractInnerSourceValue The wrapped parser's source extractor.
+* @param innerParser The wrapped parser, used to revalidate fallback values.
+* @returns The resolved source value, an async source value, or `undefined`.
+* @throws {Error} Propagates errors thrown by the env source callback
+*                 (`sourceData.source(fullKey)`).
+* @throws {Error} Propagates errors thrown by `options.parser.parse(rawValue)`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating a
+*                 successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's constraints
+*                 (see issue #414).
+*/
+function getEnvSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+	const sourceData = annotations?.[options.context.id];
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
+	const rawValue = sourceData?.source(fullKey);
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
+	if (rawValue !== void 0) {
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return {
+				success: false,
+				error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} must be a string, but got: ${type}.`
+			};
+		}
+		return (0, __optique_core_extension.mapModeValue)(options.parser.mode, options.parser.parse(rawValue), (p) => validateFallback(p));
+	}
+	if (options.default !== void 0) return validateFallback({
+		success: true,
+		value: options.default
+	});
+	return extractInnerSourceValue(innerState);
+}
 const TRUE_LITERALS = [
 	"true",
 	"1",
@@ -228,8 +386,9 @@ function bool(options = {}) {
 	const metavar = options.metavar ?? "BOOLEAN";
 	(0, __optique_core_valueparser.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: false,
 		choices: [true, false],
 		parse(input) {
 			const normalized = input.trim().toLowerCase();
@@ -243,7 +402,10 @@ function bool(options = {}) {
 			};
 			return {
 				success: false,
-				error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : __optique_core_message.message`Invalid Boolean value: ${input}. Expected one of ${(0, __optique_core_message.valueSet)([...TRUE_LITERALS, ...FALSE_LITERALS], { locale: "en-US" })}`
+				error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : __optique_core_message.message`Invalid Boolean value: ${input}. Expected one of ${(0, __optique_core_message.valueSet)([...TRUE_LITERALS, ...FALSE_LITERALS], {
+					fallback: "",
+					locale: "en-US"
+				})}`
 			};
 		},
 		format(value) {
@@ -263,7 +425,4 @@ function bool(options = {}) {
 //#endregion
 exports.bindEnv = bindEnv;
 exports.bool = bool;
-exports.clearActiveEnvSource = clearActiveEnvSource;
-exports.createEnvContext = createEnvContext;
-exports.getActiveEnvSource = getActiveEnvSource;
-exports.setActiveEnvSource = setActiveEnvSource;
+exports.createEnvContext = createEnvContext;

package/dist/index.d.cts

@@ -11,10 +11,6 @@ import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
  * @since 1.0.0
  */
 type EnvSource = (key: string) => string | undefined;
-interface EnvSourceData {
-  readonly prefix: string;
-  readonly source: EnvSource;
-}
 /**
  * Context for environment-variable-based fallback values.
  *
@@ -49,29 +45,19 @@ interface EnvContextOptions {
    */
   readonly source?: EnvSource;
 }
-/**
- * Sets active environment source data for a context.
- *
- * @internal
- */
-declare function setActiveEnvSource(contextId: symbol, sourceData: EnvSourceData): void;
-/**
- * Gets active environment source data for a context.
- *
- * @internal
- */
-declare function getActiveEnvSource(contextId: symbol): EnvSourceData | undefined;
-/**
- * Clears active environment source data for a context.
- *
- * @internal
- */
-declare function clearActiveEnvSource(contextId: symbol): void;
 /**
  * Creates an environment context for use with Optique runners.
  *
+ * When calling `context.getAnnotations()` manually, pass the returned
+ * annotations to low-level APIs such as `parse()`, `parseAsync()`,
+ * `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
+ * contexts are single-pass, `getAnnotations()` can still be called without
+ * a phase request. Calling it by itself does not affect later parses.
+ *
  * @param options Environment context options.
  * @returns A context that provides environment source annotations.
+ * @throws {TypeError} If `prefix` is not a string.
+ * @throws {TypeError} If `source` is not a function.
  * @since 1.0.0
  */
 declare function createEnvContext(options?: EnvContextOptions): EnvContext;
@@ -116,10 +102,16 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.
+ * @throws {TypeError} If `key` is not a string or `parser` is not a valid
+ *                    {@link ValueParser}.
  * @throws {Error} If the inner parser throws while parsing or completing a
  *                 value, if the environment source throws while reading a
- *                 variable, or if the environment value parser throws while
- *                 parsing the environment variable value.
+ *                 variable, if the environment value parser throws while
+ *                 parsing the environment variable value, or if the inner
+ *                 parser's {@link Parser.validateValue} hook throws while
+ *                 re-validating a fallback value (environment variable value
+ *                 or configured `default`) — the hook can run even when no
+ *                 CLI tokens are parsed (see issue #414).
  * @since 1.0.0
  */
 declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): Parser<M, TValue, TState>;
@@ -160,4 +152,4 @@ interface BoolOptions {
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
 //#endregion
-export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, clearActiveEnvSource, createEnvContext, getActiveEnvSource, setActiveEnvSource };
+export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, createEnvContext };

package/dist/index.d.ts

@@ -11,10 +11,6 @@ import { Mode, Parser } from "@optique/core/parser";
  * @since 1.0.0
  */
 type EnvSource = (key: string) => string | undefined;
-interface EnvSourceData {
-  readonly prefix: string;
-  readonly source: EnvSource;
-}
 /**
  * Context for environment-variable-based fallback values.
  *
@@ -49,29 +45,19 @@ interface EnvContextOptions {
    */
   readonly source?: EnvSource;
 }
-/**
- * Sets active environment source data for a context.
- *
- * @internal
- */
-declare function setActiveEnvSource(contextId: symbol, sourceData: EnvSourceData): void;
-/**
- * Gets active environment source data for a context.
- *
- * @internal
- */
-declare function getActiveEnvSource(contextId: symbol): EnvSourceData | undefined;
-/**
- * Clears active environment source data for a context.
- *
- * @internal
- */
-declare function clearActiveEnvSource(contextId: symbol): void;
 /**
  * Creates an environment context for use with Optique runners.
  *
+ * When calling `context.getAnnotations()` manually, pass the returned
+ * annotations to low-level APIs such as `parse()`, `parseAsync()`,
+ * `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
+ * contexts are single-pass, `getAnnotations()` can still be called without
+ * a phase request. Calling it by itself does not affect later parses.
+ *
  * @param options Environment context options.
  * @returns A context that provides environment source annotations.
+ * @throws {TypeError} If `prefix` is not a string.
+ * @throws {TypeError} If `source` is not a function.
  * @since 1.0.0
  */
 declare function createEnvContext(options?: EnvContextOptions): EnvContext;
@@ -116,10 +102,16 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.
+ * @throws {TypeError} If `key` is not a string or `parser` is not a valid
+ *                    {@link ValueParser}.
  * @throws {Error} If the inner parser throws while parsing or completing a
  *                 value, if the environment source throws while reading a
- *                 variable, or if the environment value parser throws while
- *                 parsing the environment variable value.
+ *                 variable, if the environment value parser throws while
+ *                 parsing the environment variable value, or if the inner
+ *                 parser's {@link Parser.validateValue} hook throws while
+ *                 re-validating a fallback value (environment variable value
+ *                 or configured `default`) — the hook can run even when no
+ *                 CLI tokens are parsed (see issue #414).
  * @since 1.0.0
  */
 declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): Parser<M, TValue, TState>;
@@ -160,4 +152,4 @@ interface BoolOptions {
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
 //#endregion
-export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, clearActiveEnvSource, createEnvContext, getActiveEnvSource, setActiveEnvSource };
+export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, createEnvContext };

package/dist/index.js

@@ -1,35 +1,9 @@
-import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { getAnnotations } from "@optique/core/annotations";
+import { defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, wrapForMode } from "@optique/core/extension";
 import { envVar, message, valueSet } from "@optique/core/message";
-import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
-import { ensureNonEmptyString } from "@optique/core/valueparser";
+import { ensureNonEmptyString, isValueParser } from "@optique/core/valueparser";
 
 //#region src/index.ts
-const deferPromptUntilConfigResolvesKey = Symbol.for("@optique/config/deferPromptUntilResolved");
-const activeEnvSourceRegistry = /* @__PURE__ */ new Map();
-/**
-* Sets active environment source data for a context.
-*
-* @internal
-*/
-function setActiveEnvSource(contextId, sourceData) {
-	activeEnvSourceRegistry.set(contextId, sourceData);
-}
-/**
-* Gets active environment source data for a context.
-*
-* @internal
-*/
-function getActiveEnvSource(contextId) {
-	return activeEnvSourceRegistry.get(contextId);
-}
-/**
-* Clears active environment source data for a context.
-*
-* @internal
-*/
-function clearActiveEnvSource(contextId) {
-	activeEnvSourceRegistry.delete(contextId);
-}
 function defaultEnvSource(key) {
 	const denoGlobal = globalThis.Deno;
 	if (typeof denoGlobal?.env?.get === "function") return denoGlobal.env.get(key);
@@ -39,30 +13,39 @@ function defaultEnvSource(key) {
 /**
 * Creates an environment context for use with Optique runners.
 *
+* When calling `context.getAnnotations()` manually, pass the returned
+* annotations to low-level APIs such as `parse()`, `parseAsync()`,
+* `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
+* contexts are single-pass, `getAnnotations()` can still be called without
+* a phase request. Calling it by itself does not affect later parses.
+*
 * @param options Environment context options.
 * @returns A context that provides environment source annotations.
+* @throws {TypeError} If `prefix` is not a string.
+* @throws {TypeError} If `source` is not a function.
 * @since 1.0.0
 */
 function createEnvContext(options = {}) {
 	const contextId = Symbol(`@optique/env context:${Math.random()}`);
-	const source = options.source ?? defaultEnvSource;
-	const prefix = options.prefix ?? "";
+	const rawSource = options.source;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${rawSource === null ? "null" : Array.isArray(rawSource) ? "array" : typeof rawSource}.`);
+	const source = rawSource ?? defaultEnvSource;
+	const rawPrefix = options.prefix;
+	if (rawPrefix !== void 0 && typeof rawPrefix !== "string") throw new TypeError(`Expected prefix to be a string, but got: ${rawPrefix === null ? "null" : Array.isArray(rawPrefix) ? "array" : typeof rawPrefix}.`);
+	const prefix = rawPrefix ?? "";
 	return {
 		id: contextId,
 		prefix,
 		source,
-		mode: "static",
+		phase: "single-pass",
 		getAnnotations() {
 			const sourceData = {
 				prefix,
 				source
 			};
-			setActiveEnvSource(contextId, sourceData);
 			return { [contextId]: sourceData };
 		},
-		[Symbol.dispose]() {
-			clearActiveEnvSource(contextId);
-		}
+		[Symbol.dispose]() {}
 	};
 }
 /**
@@ -78,20 +61,28 @@ function createEnvContext(options = {}) {
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
+* @throws {TypeError} If `key` is not a string or `parser` is not a valid
+*                    {@link ValueParser}.
 * @throws {Error} If the inner parser throws while parsing or completing a
 *                 value, if the environment source throws while reading a
-*                 variable, or if the environment value parser throws while
-*                 parsing the environment variable value.
+*                 variable, if the environment value parser throws while
+*                 parsing the environment variable value, or if the inner
+*                 parser's {@link Parser.validateValue} hook throws while
+*                 re-validating a fallback value (environment variable value
+*                 or configured `default`) — the hook can run even when no
+*                 CLI tokens are parsed (see issue #414).
 * @since 1.0.0
 */
 function bindEnv(parser, options) {
+	if (typeof options.key !== "string") throw new TypeError(`Expected key to be a string, but got: ${options.key === null ? "null" : Array.isArray(options.key) ? "array" : typeof options.key}.`);
+	if (!isValueParser(options.parser)) throw new TypeError(`Expected parser to be a ValueParser, but got: ${options.parser === null ? "null" : Array.isArray(options.parser) ? "array" : typeof options.parser}.`);
 	const envBindStateKey = Symbol("@optique/env/bindState");
 	function isEnvBindState(value) {
 		return value != null && typeof value === "object" && envBindStateKey in value;
 	}
-	const deferPromptUntilConfigResolves = Reflect.get(parser, deferPromptUntilConfigResolvesKey);
-	return {
-		$mode: parser.$mode,
+	const deferPromptUntilConfigResolves = parser.shouldDeferCompletion;
+	const boundParser = {
+		mode: parser.mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
@@ -99,7 +90,13 @@ function bindEnv(parser, options) {
 			type: "optional",
 			terms: parser.usage
 		}] : parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = isEnvBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+			return delegateSuggestNodes(parser, boundParser, state, path, innerState);
+		},
 		parse: (context) => {
 			const annotations = getAnnotations(context.state);
 			const innerState = isEnvBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
@@ -110,14 +107,14 @@ function bindEnv(parser, options) {
 			const processResult = (result) => {
 				if (result.success) {
 					const cliConsumed = result.consumed.length > 0;
-					const nextState$1 = {
+					const nextState$1 = injectAnnotations({
 						[envBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result.next.state,
-						...annotations && { [annotationKey]: annotations }
-					};
+						cliState: result.next.state
+					}, annotations);
 					return {
 						success: true,
+						...result.provisional ? { provisional: true } : {},
 						next: {
 							...result.next,
 							state: nextState$1
@@ -126,11 +123,10 @@ function bindEnv(parser, options) {
 					};
 				}
 				if (result.consumed > 0) return result;
-				const nextState = {
+				const nextState = injectAnnotations({
 					[envBindStateKey]: true,
-					hasCliValue: false,
-					...annotations && { [annotationKey]: annotations }
-				};
+					hasCliValue: false
+				}, annotations);
 				return {
 					success: true,
 					next: {
@@ -140,42 +136,204 @@ function bindEnv(parser, options) {
 					consumed: []
 				};
 			};
-			return mapModeValue(parser.$mode, parser.parse(innerContext), processResult);
+			return mapModeValue(parser.mode, parser.parse(innerContext), processResult);
 		},
-		complete: (state) => {
-			if (isEnvBindState(state) && state.hasCliValue) return parser.complete(state.cliState);
-			return getEnvOrDefault(state, options, parser.$mode, parser, isEnvBindState(state) ? state.cliState : void 0);
+		complete: (state, exec) => {
+			if (isEnvBindState(state) && state.hasCliValue) return parser.complete(state.cliState, exec);
+			return getEnvOrDefault(state, options, parser.mode, parser, isEnvBindState(state) ? state.cliState : isInjectedAnnotationState(state) ? void 0 : state, exec);
 		},
 		suggest: parser.suggest,
-		...typeof deferPromptUntilConfigResolves === "function" ? { [deferPromptUntilConfigResolvesKey]: (state) => deferPromptUntilConfigResolves(state) } : {},
+		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: (state, exec) => deferPromptUntilConfigResolves.call(parser, state, exec) } : {},
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	defineTraits(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(boundParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = mapSourceMetadata(parser, (sourceMetadata) => ({
+		...sourceMetadata,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return parser.validateValue(options.default);
+			return {
+				success: true,
+				value: options.default
+			};
+		} : void 0,
+		extractSourceValue: (state) => {
+			if (!isEnvBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
+				return sourceMetadata.extractSourceValue(state);
+			}
+			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
+			const innerState = state.cliState ?? state;
+			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(innerState);
+			return getEnvSourceValue(state, options, innerState, sourceMetadata.extractSourceValue, parser);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
+	return boundParser;
 }
-function getEnvOrDefault(state, options, mode, innerParser, innerState) {
+/**
+* Resolves a `bindEnv()` fallback value with env > default > inner
+* `complete()` priority, running each candidate through the inner
+* parser's `validateValue()` hook when available so the inner CLI
+* parser's constraints are enforced on fallback values (see issue
+* #414).
+*
+* @param state The wrapper state, which may carry env annotations.
+* @param options The binding options with lookup and default settings.
+* @param mode The parser mode (`"sync"` or `"async"`), used to
+*             dispatch env parsing and fallback validation.
+* @param innerParser Optional wrapped parser.  When present, its
+*                    `validateValue()` hook is used to re-validate
+*                    fallback values and its `complete()` is
+*                    delegated to as the last fallback.
+* @param innerState Optional unwrapped inner state to pass through to
+*                   `innerParser.complete()`.
+* @param exec Optional execution context forwarded to
+*             `innerParser.complete()`.
+* @returns The resolved value as a mode-dependent result.
+* @throws {Error} Propagates errors thrown by the env source callback
+*                 (`sourceData.source(fullKey)`) while reading the
+*                 environment variable.
+* @throws {Error} Propagates errors thrown by
+*                 `options.parser.parse(rawValue)` (sync or async)
+*                 while parsing the raw env string into `TValue`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while re-validating
+*                 a successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's
+*                 constraints.
+* @throws {Error} Propagates errors thrown by `innerParser.complete()`
+*                 when falling through to the inner parser (e.g.,
+*                 `bindEnv(bindConfig(...))` with neither env nor
+*                 default set).
+*/
+function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 	const annotations = getAnnotations(state);
-	const sourceData = annotations?.[options.context.id] ?? getActiveEnvSource(options.context.id);
+	const sourceData = annotations?.[options.context.id];
 	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
 	const rawValue = sourceData?.source(fullKey);
+	const validateSync = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
+	const validateAsync = async (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return await innerParser.validateValue(parsed.value);
+	};
 	if (rawValue !== void 0) {
-		const parsed = options.parser.parse(rawValue);
-		return wrapForMode(mode, parsed);
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return wrapForMode(mode, {
+				success: false,
+				error: message`Environment variable ${envVar(fullKey)} must be a string, but got: ${type}.`
+			});
+		}
+		return dispatchByMode(mode, () => {
+			const parsed = options.parser.parse(rawValue);
+			return validateSync(parsed);
+		}, async () => {
+			const parsed = await options.parser.parse(rawValue);
+			return await validateAsync(parsed);
+		});
 	}
-	if (options.default !== void 0) return wrapForMode(mode, {
+	if (options.default !== void 0) return dispatchByMode(mode, () => validateSync({
 		success: true,
 		value: options.default
-	});
+	}), () => validateAsync({
+		success: true,
+		value: options.default
+	}));
 	if (innerParser != null) {
-		const completeState = innerState ?? innerParser.initialState;
-		return wrapForMode(mode, innerParser.complete(completeState));
+		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && getTraits(innerParser).inheritsAnnotations === true ? injectAnnotations(innerParser.initialState, annotations) : innerParser.initialState);
+		return wrapForMode(mode, innerParser.complete(completeState, exec));
 	}
 	return wrapForMode(mode, {
 		success: false,
 		error: message`Missing required environment variable: ${envVar(fullKey)}`
 	});
 }
+/**
+* Resolves an env-backed dependency source with env and default fallbacks.
+*
+* This first checks annotations for the bound variable. If no env-backed value
+* is available, it falls back to `options.default` and finally delegates to
+* the wrapped parser's source extractor.
+*
+* When `innerParser` exposes a `validateValue` hook, env-sourced values
+* and the configured default are re-validated against the inner parser's
+* CLI constraints (see issue #414).  This is only called from the
+* `preservesSourceValue: true` branch in {@link bindEnv}, so the source
+* value type is guaranteed to equal `TValue`.
+*
+* @param state The wrapper state, which may carry env annotations.
+* @param options The binding options with lookup and default settings.
+* @param innerState The unwrapped inner state for delegated extraction.
+* @param extractInnerSourceValue The wrapped parser's source extractor.
+* @param innerParser The wrapped parser, used to revalidate fallback values.
+* @returns The resolved source value, an async source value, or `undefined`.
+* @throws {Error} Propagates errors thrown by the env source callback
+*                 (`sourceData.source(fullKey)`).
+* @throws {Error} Propagates errors thrown by `options.parser.parse(rawValue)`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating a
+*                 successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's constraints
+*                 (see issue #414).
+*/
+function getEnvSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
+	const annotations = getAnnotations(state);
+	const sourceData = annotations?.[options.context.id];
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
+	const rawValue = sourceData?.source(fullKey);
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
+	if (rawValue !== void 0) {
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return {
+				success: false,
+				error: message`Environment variable ${envVar(fullKey)} must be a string, but got: ${type}.`
+			};
+		}
+		return mapModeValue(options.parser.mode, options.parser.parse(rawValue), (p) => validateFallback(p));
+	}
+	if (options.default !== void 0) return validateFallback({
+		success: true,
+		value: options.default
+	});
+	return extractInnerSourceValue(innerState);
+}
 const TRUE_LITERALS = [
 	"true",
 	"1",
@@ -205,8 +363,9 @@ function bool(options = {}) {
 	const metavar = options.metavar ?? "BOOLEAN";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: false,
 		choices: [true, false],
 		parse(input) {
 			const normalized = input.trim().toLowerCase();
@@ -220,7 +379,10 @@ function bool(options = {}) {
 			};
 			return {
 				success: false,
-				error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : message`Invalid Boolean value: ${input}. Expected one of ${valueSet([...TRUE_LITERALS, ...FALSE_LITERALS], { locale: "en-US" })}`
+				error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : message`Invalid Boolean value: ${input}. Expected one of ${valueSet([...TRUE_LITERALS, ...FALSE_LITERALS], {
+					fallback: "",
+					locale: "en-US"
+				})}`
 			};
 		},
 		format(value) {
@@ -238,4 +400,4 @@ function bool(options = {}) {
 }
 
 //#endregion
-export { bindEnv, bool, clearActiveEnvSource, createEnvContext, getActiveEnvSource, setActiveEnvSource };
+export { bindEnv, bool, createEnvContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.0.0-dev.921+754748bd",
+  "version": "1.0.1",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -54,7 +54,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.0-dev.921+754748bd"
+    "@optique/core": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",