@optique/env 1.0.0-dev.1616 → 1.0.0-dev.1659

package/dist/index.cjs

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
 const __optique_core_message = __toESM(require("@optique/core/message"));
 const __optique_core_mode_dispatch = __toESM(require("@optique/core/mode-dispatch"));
+const __optique_core_parser = __toESM(require("@optique/core/parser"));
 const __optique_core_valueparser = __toESM(require("@optique/core/valueparser"));
 
 //#region src/index.ts
@@ -127,6 +128,7 @@ function bindEnv(parser, options) {
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
+		[__optique_core_parser.unmatchedNonCliDependencySourceStateMarker]: true,
 		usage: options.default !== void 0 ? [{
 			type: "optional",
 			terms: parser.usage
@@ -134,6 +136,10 @@ function bindEnv(parser, options) {
 		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_parser.getDelegatingSuggestRuntimeNodes)(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;
@@ -178,7 +184,7 @@ function bindEnv(parser, options) {
 		},
 		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 : void 0, exec);
+			return getEnvOrDefault(state, options, parser.$mode, parser, isEnvBindState(state) ? state.cliState : (0, __optique_core_annotations.isInjectedAnnotationWrapper)(state) ? void 0 : state, exec);
 		},
 		suggest: parser.suggest,
 		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: (state, exec) => deferPromptUntilConfigResolves.call(parser, state, exec) } : {},
@@ -187,6 +193,7 @@ function bindEnv(parser, options) {
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	(0, __optique_core_parser.defineInheritedAnnotationParser)(boundParser);
 	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -199,6 +206,24 @@ function bindEnv(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	const dependencyMetadata = (0, __optique_core_parser.composeWrappedSourceMetadata)(parser.dependencyMetadata, (sourceMetadata) => ({
+		...sourceMetadata,
+		extractSourceValue: (state) => {
+			if (!isEnvBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue);
+				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);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return boundParser;
 }
 function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
@@ -222,7 +247,7 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 		value: options.default
 	});
 	if (innerParser != null) {
-		const completeState = innerState ?? innerParser.initialState;
+		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && Reflect.get(innerParser, __optique_core_parser.inheritParentAnnotationsKey) === true ? (0, __optique_core_annotations.injectAnnotations)(innerParser.initialState, annotations) : innerParser.initialState);
 		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, innerParser.complete(completeState, exec));
 	}
 	return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
@@ -230,6 +255,45 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 		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 or the active env registry 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.
+*
+* @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.
+* @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)`.
+*/
+function getEnvSourceValue(state, options, innerState, extractInnerSourceValue) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+	const sourceData = annotations?.[options.context.id] ?? getActiveEnvSource(options.context.id);
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
+	const rawValue = sourceData?.source(fullKey);
+	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}.`
+			};
+		}
+		const parsed = options.parser.parse(rawValue);
+		return parsed;
+	}
+	if (options.default !== void 0) return {
+		success: true,
+		value: options.default
+	};
+	return extractInnerSourceValue(innerState);
+}
 const TRUE_LITERALS = [
 	"true",
 	"1",

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Message } from "@optique/core/message";
+import { Mode, Parser } from "@optique/core/parser";
 import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
 import { SourceContext } from "@optique/core/context";
-import { Mode, Parser } from "@optique/core/parser";
 
 //#region src/index.d.ts
 

package/dist/index.js

@@ -1,6 +1,7 @@
-import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { annotationKey, getAnnotations, injectAnnotations, isInjectedAnnotationWrapper } from "@optique/core/annotations";
 import { envVar, message, valueSet } from "@optique/core/message";
 import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
+import { composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "@optique/core/parser";
 import { ensureNonEmptyString, isValueParser } from "@optique/core/valueparser";
 
 //#region src/index.ts
@@ -104,6 +105,7 @@ function bindEnv(parser, options) {
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
+		[unmatchedNonCliDependencySourceStateMarker]: true,
 		usage: options.default !== void 0 ? [{
 			type: "optional",
 			terms: parser.usage
@@ -111,6 +113,10 @@ function bindEnv(parser, options) {
 		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 getDelegatingSuggestRuntimeNodes(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;
@@ -155,7 +161,7 @@ function bindEnv(parser, options) {
 		},
 		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 : void 0, exec);
+			return getEnvOrDefault(state, options, parser.$mode, parser, isEnvBindState(state) ? state.cliState : isInjectedAnnotationWrapper(state) ? void 0 : state, exec);
 		},
 		suggest: parser.suggest,
 		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: (state, exec) => deferPromptUntilConfigResolves.call(parser, state, exec) } : {},
@@ -164,6 +170,7 @@ function bindEnv(parser, options) {
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	defineInheritedAnnotationParser(boundParser);
 	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -176,6 +183,24 @@ function bindEnv(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	const dependencyMetadata = composeWrappedSourceMetadata(parser.dependencyMetadata, (sourceMetadata) => ({
+		...sourceMetadata,
+		extractSourceValue: (state) => {
+			if (!isEnvBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue);
+				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);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return boundParser;
 }
 function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
@@ -199,7 +224,7 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 		value: options.default
 	});
 	if (innerParser != null) {
-		const completeState = innerState ?? innerParser.initialState;
+		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && Reflect.get(innerParser, inheritParentAnnotationsKey) === true ? injectAnnotations(innerParser.initialState, annotations) : innerParser.initialState);
 		return wrapForMode(mode, innerParser.complete(completeState, exec));
 	}
 	return wrapForMode(mode, {
@@ -207,6 +232,45 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 		error: message`Missing required environment variable: ${envVar(fullKey)}`
 	});
 }
+/**
+* Resolves an env-backed dependency source with env and default fallbacks.
+*
+* This first checks annotations or the active env registry 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.
+*
+* @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.
+* @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)`.
+*/
+function getEnvSourceValue(state, options, innerState, extractInnerSourceValue) {
+	const annotations = getAnnotations(state);
+	const sourceData = annotations?.[options.context.id] ?? getActiveEnvSource(options.context.id);
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
+	const rawValue = sourceData?.source(fullKey);
+	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}.`
+			};
+		}
+		const parsed = options.parser.parse(rawValue);
+		return parsed;
+	}
+	if (options.default !== void 0) return {
+		success: true,
+		value: options.default
+	};
+	return extractInnerSourceValue(innerState);
+}
 const TRUE_LITERALS = [
 	"true",
 	"1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.0.0-dev.1616+17abc525",
+  "version": "1.0.0-dev.1659+94dcbc28",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -54,7 +54,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.0-dev.1616+17abc525"
+    "@optique/core": "1.0.0-dev.1659+94dcbc28"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",