@optique/env 1.0.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+@optique/env
+============
+
+Environment variable support for [Optique].
+
+This package provides a type-safe way to bind CLI parsers to environment
+variables with clear fallback behavior:
+
+CLI arguments > environment variables > defaults.
+
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/env
+npm add @optique/env
+pnpm add @optique/env
+yarn add @optique/env
+bun add @optique/env
+~~~~
+
+
+Quick start
+-----------
+
+~~~~ typescript
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
+import { integer, string } from "@optique/core/valueparser";
+import { runAsync } from "@optique/run";
+import { bindEnv, bool, createEnvContext } from "@optique/env";
+
+const envContext = createEnvContext({ prefix: "MYAPP_" });
+
+const parser = object({
+  host: bindEnv(option("--host", string()), {
+    context: envContext,
+    key: "HOST",
+    parser: string(),
+    default: "localhost",
+  }),
+  port: bindEnv(option("--port", integer()), {
+    context: envContext,
+    key: "PORT",
+    parser: integer(),
+    default: 3000,
+  }),
+  verbose: bindEnv(option("--verbose", bool()), {
+    context: envContext,
+    key: "VERBOSE",
+    parser: bool(),
+    default: false,
+  }),
+});
+
+const result = await runAsync(parser, {
+  contexts: [envContext],
+});
+
+console.log(result);
+~~~~
+
+
+Features
+--------
+
+ -  *Type-safe env parsing* with any Optique `ValueParser`
+ -  *Common Boolean parser* via `bool()`
+ -  *Prefix support* for namespaced environment variables
+ -  *Custom env source* for Deno, tests, and custom runtimes
+ -  *Composable contexts* with `run()` / `runAsync()` / `runWith()`
+
+
+Documentation
+-------------
+
+For full documentation, visit <https://optique.dev/integrations/env>.
+
+
+License
+-------
+
+MIT License. See [LICENSE](../../LICENSE) for details.

package/dist/index.cjs

@@ -0,0 +1,260 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_message = __toESM(require("@optique/core/message"));
+const __optique_core_valueparser = __toESM(require("@optique/core/valueparser"));
+
+//#region src/index.ts
+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);
+	const processGlobal = globalThis.process;
+	return processGlobal?.env?.[key];
+}
+/**
+* Creates an environment context for use with Optique runners.
+*
+* @param options Environment context options.
+* @returns A context that provides environment source annotations.
+* @since 1.0.0
+*/
+function createEnvContext(options = {}) {
+	const contextId = Symbol(`@optique/env context:${Math.random()}`);
+	const source = options.source ?? defaultEnvSource;
+	const prefix = options.prefix ?? "";
+	return {
+		id: contextId,
+		prefix,
+		source,
+		getAnnotations() {
+			const sourceData = {
+				prefix,
+				source
+			};
+			setActiveEnvSource(contextId, sourceData);
+			return { [contextId]: sourceData };
+		},
+		[Symbol.dispose]() {
+			clearActiveEnvSource(contextId);
+		}
+	};
+}
+/**
+* Binds a parser to environment variables with fallback behavior.
+*
+* Priority order:
+*
+*  1. CLI argument value
+*  2. Environment variable value
+*  3. Default value
+*  4. Error
+*
+* @param parser Parser that reads CLI values.
+* @param options Environment binding options.
+* @returns A parser with environment fallback behavior.
+* @since 1.0.0
+*/
+function bindEnv(parser, options) {
+	const envBindStateKey = Symbol("@optique/env/bindState");
+	function isEnvBindState(value) {
+		return value != null && typeof value === "object" && envBindStateKey in value;
+	}
+	return {
+		$mode: parser.$mode,
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: options.default !== void 0 ? [{
+			type: "optional",
+			terms: parser.usage
+		}] : parser.usage,
+		initialState: parser.initialState,
+		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;
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			const processResult = (result$1) => {
+				if (result$1.success) {
+					const cliConsumed = result$1.consumed.length > 0;
+					const nextState$1 = {
+						[envBindStateKey]: true,
+						hasCliValue: cliConsumed,
+						cliState: result$1.next.state,
+						...annotations && { [__optique_core_annotations.annotationKey]: annotations }
+					};
+					return {
+						success: true,
+						next: {
+							...result$1.next,
+							state: nextState$1
+						},
+						consumed: result$1.consumed
+					};
+				}
+				if (result$1.consumed > 0) return result$1;
+				const nextState = {
+					[envBindStateKey]: true,
+					hasCliValue: false,
+					...annotations && { [__optique_core_annotations.annotationKey]: annotations }
+				};
+				return {
+					success: true,
+					next: {
+						...innerContext,
+						state: nextState
+					},
+					consumed: []
+				};
+			};
+			const result = parser.parse(innerContext);
+			if (result instanceof Promise) return result.then(processResult);
+			return processResult(result);
+		},
+		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);
+		},
+		suggest: parser.suggest,
+		getDocFragments(state, upperDefaultValue) {
+			const defaultValue = upperDefaultValue ?? options.default;
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+function wrapForMode(mode, value) {
+	if (mode === "async") return Promise.resolve(value);
+	return value;
+}
+function getEnvOrDefault(state, options, mode, innerParser, innerState) {
+	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) {
+		const parsed = options.parser.parse(rawValue);
+		if (parsed instanceof Promise) return parsed;
+		return wrapForMode(mode, parsed);
+	}
+	if (options.default !== void 0) return wrapForMode(mode, {
+		success: true,
+		value: options.default
+	});
+	if (innerParser != null) {
+		const completeState = innerState ?? innerParser.initialState;
+		const result = innerParser.complete(completeState);
+		if (result instanceof Promise) return result;
+		return wrapForMode(mode, result);
+	}
+	return wrapForMode(mode, {
+		success: false,
+		error: __optique_core_message.message`Missing required environment variable: ${fullKey}.`
+	});
+}
+const TRUE_LITERALS = [
+	"true",
+	"1",
+	"yes",
+	"on"
+];
+const FALSE_LITERALS = [
+	"false",
+	"0",
+	"no",
+	"off"
+];
+/**
+* Creates a Boolean value parser that accepts common true/false literals.
+*
+* Accepted values (case-insensitive):
+*
+*  -  True: `true`, `1`, `yes`, `on`
+*  -  False: `false`, `0`, `no`, `off`
+*
+* @param options Parser configuration options.
+* @returns A value parser for Boolean values.
+* @since 1.0.0
+*/
+function bool(options = {}) {
+	const metavar = options.metavar ?? "BOOLEAN";
+	(0, __optique_core_valueparser.ensureNonEmptyString)(metavar);
+	return {
+		$mode: "sync",
+		metavar,
+		choices: [true, false],
+		parse(input) {
+			const normalized = input.trim().toLowerCase();
+			if (TRUE_LITERALS.includes(normalized)) return {
+				success: true,
+				value: true
+			};
+			if (FALSE_LITERALS.includes(normalized)) return {
+				success: true,
+				value: false
+			};
+			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" })}`
+			};
+		},
+		format(value) {
+			return value ? "true" : "false";
+		}
+	};
+}
+
+//#endregion
+exports.bindEnv = bindEnv;
+exports.bool = bool;
+exports.clearActiveEnvSource = clearActiveEnvSource;
+exports.createEnvContext = createEnvContext;
+exports.getActiveEnvSource = getActiveEnvSource;
+exports.setActiveEnvSource = setActiveEnvSource;

package/dist/index.d.cts

@@ -0,0 +1,154 @@
+import { SourceContext } from "@optique/core/context";
+import { Message } from "@optique/core/message";
+import { Mode, Parser } from "@optique/core/parser";
+import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
+
+//#region src/index.d.ts
+
+/**
+ * Function type for reading environment variable values.
+ *
+ * @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.
+ *
+ * @since 1.0.0
+ */
+interface EnvContext extends SourceContext {
+  /**
+   * Prefix added to all bound keys.
+   */
+  readonly prefix: string;
+  /**
+   * Environment value source for this context.
+   */
+  readonly source: EnvSource;
+}
+/**
+ * Options for creating an environment context.
+ *
+ * @since 1.0.0
+ */
+interface EnvContextOptions {
+  /**
+   * Optional prefix added to all environment keys.
+   *
+   * @default ""
+   */
+  readonly prefix?: string;
+  /**
+   * Custom environment source function.
+   *
+   * @default Runtime-specific source (`Deno.env.get` or `process.env`)
+   */
+  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.
+ *
+ * @param options Environment context options.
+ * @returns A context that provides environment source annotations.
+ * @since 1.0.0
+ */
+declare function createEnvContext(options?: EnvContextOptions): EnvContext;
+/**
+ * Options for binding a parser to environment values.
+ *
+ * @template TValue The parser value type.
+ * @since 1.0.0
+ */
+interface BindEnvOptions<M extends Mode, TValue> {
+  /**
+   * The environment context to read from.
+   */
+  readonly context: EnvContext;
+  /**
+   * Environment variable key without prefix.
+   */
+  readonly key: string;
+  /**
+   * Value parser used to parse the environment variable string value.
+   */
+  readonly parser: ValueParser<M extends "sync" ? "sync" : Mode, TValue>;
+  /**
+   * Default value used when neither CLI nor environment provides a value.
+   */
+  readonly default?: TValue;
+}
+/**
+ * Binds a parser to environment variables with fallback behavior.
+ *
+ * Priority order:
+ *
+ *  1. CLI argument value
+ *  2. Environment variable value
+ *  3. Default value
+ *  4. Error
+ *
+ * @param parser Parser that reads CLI values.
+ * @param options Environment binding options.
+ * @returns A parser with environment fallback behavior.
+ * @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>;
+/**
+ * Options for the {@link bool} parser.
+ *
+ * @since 1.0.0
+ */
+interface BoolOptions {
+  /**
+   * The metavariable name shown in help text.
+   *
+   * @default "BOOLEAN"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Custom error messages for invalid Boolean input.
+   */
+  readonly errors?: {
+    /**
+     * Custom error when input is not a recognized Boolean literal.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a Boolean value parser that accepts common true/false literals.
+ *
+ * Accepted values (case-insensitive):
+ *
+ *  -  True: `true`, `1`, `yes`, `on`
+ *  -  False: `false`, `0`, `no`, `off`
+ *
+ * @param options Parser configuration options.
+ * @returns A value parser for Boolean values.
+ * @since 1.0.0
+ */
+declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
+//#endregion
+export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, clearActiveEnvSource, createEnvContext, getActiveEnvSource, setActiveEnvSource };

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import { Message } from "@optique/core/message";
+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
+
+/**
+ * Function type for reading environment variable values.
+ *
+ * @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.
+ *
+ * @since 1.0.0
+ */
+interface EnvContext extends SourceContext {
+  /**
+   * Prefix added to all bound keys.
+   */
+  readonly prefix: string;
+  /**
+   * Environment value source for this context.
+   */
+  readonly source: EnvSource;
+}
+/**
+ * Options for creating an environment context.
+ *
+ * @since 1.0.0
+ */
+interface EnvContextOptions {
+  /**
+   * Optional prefix added to all environment keys.
+   *
+   * @default ""
+   */
+  readonly prefix?: string;
+  /**
+   * Custom environment source function.
+   *
+   * @default Runtime-specific source (`Deno.env.get` or `process.env`)
+   */
+  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.
+ *
+ * @param options Environment context options.
+ * @returns A context that provides environment source annotations.
+ * @since 1.0.0
+ */
+declare function createEnvContext(options?: EnvContextOptions): EnvContext;
+/**
+ * Options for binding a parser to environment values.
+ *
+ * @template TValue The parser value type.
+ * @since 1.0.0
+ */
+interface BindEnvOptions<M extends Mode, TValue> {
+  /**
+   * The environment context to read from.
+   */
+  readonly context: EnvContext;
+  /**
+   * Environment variable key without prefix.
+   */
+  readonly key: string;
+  /**
+   * Value parser used to parse the environment variable string value.
+   */
+  readonly parser: ValueParser<M extends "sync" ? "sync" : Mode, TValue>;
+  /**
+   * Default value used when neither CLI nor environment provides a value.
+   */
+  readonly default?: TValue;
+}
+/**
+ * Binds a parser to environment variables with fallback behavior.
+ *
+ * Priority order:
+ *
+ *  1. CLI argument value
+ *  2. Environment variable value
+ *  3. Default value
+ *  4. Error
+ *
+ * @param parser Parser that reads CLI values.
+ * @param options Environment binding options.
+ * @returns A parser with environment fallback behavior.
+ * @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>;
+/**
+ * Options for the {@link bool} parser.
+ *
+ * @since 1.0.0
+ */
+interface BoolOptions {
+  /**
+   * The metavariable name shown in help text.
+   *
+   * @default "BOOLEAN"
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Custom error messages for invalid Boolean input.
+   */
+  readonly errors?: {
+    /**
+     * Custom error when input is not a recognized Boolean literal.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a Boolean value parser that accepts common true/false literals.
+ *
+ * Accepted values (case-insensitive):
+ *
+ *  -  True: `true`, `1`, `yes`, `on`
+ *  -  False: `false`, `0`, `no`, `off`
+ *
+ * @param options Parser configuration options.
+ * @returns A value parser for Boolean values.
+ * @since 1.0.0
+ */
+declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
+//#endregion
+export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, clearActiveEnvSource, createEnvContext, getActiveEnvSource, setActiveEnvSource };

package/dist/index.js

@@ -0,0 +1,232 @@
+import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { message, valueSet } from "@optique/core/message";
+import { ensureNonEmptyString } from "@optique/core/valueparser";
+
+//#region src/index.ts
+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);
+	const processGlobal = globalThis.process;
+	return processGlobal?.env?.[key];
+}
+/**
+* Creates an environment context for use with Optique runners.
+*
+* @param options Environment context options.
+* @returns A context that provides environment source annotations.
+* @since 1.0.0
+*/
+function createEnvContext(options = {}) {
+	const contextId = Symbol(`@optique/env context:${Math.random()}`);
+	const source = options.source ?? defaultEnvSource;
+	const prefix = options.prefix ?? "";
+	return {
+		id: contextId,
+		prefix,
+		source,
+		getAnnotations() {
+			const sourceData = {
+				prefix,
+				source
+			};
+			setActiveEnvSource(contextId, sourceData);
+			return { [contextId]: sourceData };
+		},
+		[Symbol.dispose]() {
+			clearActiveEnvSource(contextId);
+		}
+	};
+}
+/**
+* Binds a parser to environment variables with fallback behavior.
+*
+* Priority order:
+*
+*  1. CLI argument value
+*  2. Environment variable value
+*  3. Default value
+*  4. Error
+*
+* @param parser Parser that reads CLI values.
+* @param options Environment binding options.
+* @returns A parser with environment fallback behavior.
+* @since 1.0.0
+*/
+function bindEnv(parser, options) {
+	const envBindStateKey = Symbol("@optique/env/bindState");
+	function isEnvBindState(value) {
+		return value != null && typeof value === "object" && envBindStateKey in value;
+	}
+	return {
+		$mode: parser.$mode,
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: options.default !== void 0 ? [{
+			type: "optional",
+			terms: parser.usage
+		}] : parser.usage,
+		initialState: parser.initialState,
+		parse: (context) => {
+			const annotations = getAnnotations(context.state);
+			const innerState = isEnvBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			const processResult = (result$1) => {
+				if (result$1.success) {
+					const cliConsumed = result$1.consumed.length > 0;
+					const nextState$1 = {
+						[envBindStateKey]: true,
+						hasCliValue: cliConsumed,
+						cliState: result$1.next.state,
+						...annotations && { [annotationKey]: annotations }
+					};
+					return {
+						success: true,
+						next: {
+							...result$1.next,
+							state: nextState$1
+						},
+						consumed: result$1.consumed
+					};
+				}
+				if (result$1.consumed > 0) return result$1;
+				const nextState = {
+					[envBindStateKey]: true,
+					hasCliValue: false,
+					...annotations && { [annotationKey]: annotations }
+				};
+				return {
+					success: true,
+					next: {
+						...innerContext,
+						state: nextState
+					},
+					consumed: []
+				};
+			};
+			const result = parser.parse(innerContext);
+			if (result instanceof Promise) return result.then(processResult);
+			return processResult(result);
+		},
+		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);
+		},
+		suggest: parser.suggest,
+		getDocFragments(state, upperDefaultValue) {
+			const defaultValue = upperDefaultValue ?? options.default;
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+function wrapForMode(mode, value) {
+	if (mode === "async") return Promise.resolve(value);
+	return value;
+}
+function getEnvOrDefault(state, options, mode, innerParser, innerState) {
+	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) {
+		const parsed = options.parser.parse(rawValue);
+		if (parsed instanceof Promise) return parsed;
+		return wrapForMode(mode, parsed);
+	}
+	if (options.default !== void 0) return wrapForMode(mode, {
+		success: true,
+		value: options.default
+	});
+	if (innerParser != null) {
+		const completeState = innerState ?? innerParser.initialState;
+		const result = innerParser.complete(completeState);
+		if (result instanceof Promise) return result;
+		return wrapForMode(mode, result);
+	}
+	return wrapForMode(mode, {
+		success: false,
+		error: message`Missing required environment variable: ${fullKey}.`
+	});
+}
+const TRUE_LITERALS = [
+	"true",
+	"1",
+	"yes",
+	"on"
+];
+const FALSE_LITERALS = [
+	"false",
+	"0",
+	"no",
+	"off"
+];
+/**
+* Creates a Boolean value parser that accepts common true/false literals.
+*
+* Accepted values (case-insensitive):
+*
+*  -  True: `true`, `1`, `yes`, `on`
+*  -  False: `false`, `0`, `no`, `off`
+*
+* @param options Parser configuration options.
+* @returns A value parser for Boolean values.
+* @since 1.0.0
+*/
+function bool(options = {}) {
+	const metavar = options.metavar ?? "BOOLEAN";
+	ensureNonEmptyString(metavar);
+	return {
+		$mode: "sync",
+		metavar,
+		choices: [true, false],
+		parse(input) {
+			const normalized = input.trim().toLowerCase();
+			if (TRUE_LITERALS.includes(normalized)) return {
+				success: true,
+				value: true
+			};
+			if (FALSE_LITERALS.includes(normalized)) return {
+				success: true,
+				value: false
+			};
+			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" })}`
+			};
+		},
+		format(value) {
+			return value ? "true" : "false";
+		}
+	};
+}
+
+//#endregion
+export { bindEnv, bool, clearActiveEnvSource, createEnvContext, getActiveEnvSource, setActiveEnvSource };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@optique/env",
+  "version": "1.0.0-dev.0",
+  "description": "Environment variable support for Optique",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "environment",
+    "env"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/env/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@optique/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --experimental-transform-types --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}