@optique/env 1.1.0-dev.2087 → 1.1.0-dev.2146

package/README.md

@@ -6,7 +6,7 @@ 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.
+CLI arguments > environment variables > *.env* files > defaults.
 
 [Optique]: https://optique.dev/
 
@@ -33,7 +33,10 @@ 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 envContext = createEnvContext({
+  prefix: "MYAPP_",
+  envFile: [".env", ".env.local"],
+});
 
 const parser = object({
   host: bindEnv(option("--host", string()), {
@@ -70,6 +73,7 @@ Features
  -  *Type-safe env parsing* with any Optique `ValueParser`
  -  *Common Boolean parser* via `bool()`
  -  *Prefix support* for namespaced environment variables
+ -  *.env file loading* without mutating `process.env` or `Deno.env`
  -  *Custom env source* for Deno, tests, and custom runtimes
  -  *Composable contexts* with `run()`/`runAsync()`/`runWith()`
 

package/dist/index.cjs

@@ -21,18 +21,232 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+const node_fs = __toESM(require("node:fs"));
+const node_path = __toESM(require("node:path"));
 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_valueparser = __toESM(require("@optique/core/valueparser"));
 
 //#region src/index.ts
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
 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];
 }
+function isErrnoException(error) {
+	return error != null && typeof error === "object" && "code" in error && typeof error.code === "string";
+}
+function normalizeEnvFilePaths(paths) {
+	if (paths === false) return [];
+	if (paths === true) return [".env"];
+	if (typeof paths === "string") return [paths];
+	if (Array.isArray(paths)) {
+		for (const path of paths) if (typeof path !== "string") throw new TypeError(`Expected envFile paths to be strings, but got: ${getTypeName(path)}.`);
+		return paths;
+	}
+	throw new TypeError(`Expected envFile.paths to be a boolean, string, array, or undefined, but got: ${getTypeName(paths)}.`);
+}
+function normalizeEnvFileOptions(envFile) {
+	if (envFile === void 0 || envFile === false) return { paths: [] };
+	if (envFile === true || typeof envFile === "string" || Array.isArray(envFile)) return { paths: normalizeEnvFilePaths(envFile) };
+	if (envFile == null || typeof envFile !== "object") throw new TypeError(`Expected envFile to be a boolean, string, array, or object, but got: ${getTypeName(envFile)}.`);
+	const options = envFile;
+	const rawSubstitute = options.substitute;
+	if (rawSubstitute !== void 0 && typeof rawSubstitute !== "function") throw new TypeError(`Expected envFile.substitute to be a function or undefined, but got: ${getTypeName(rawSubstitute)}.`);
+	return {
+		paths: normalizeEnvFilePaths(options.paths ?? true),
+		...rawSubstitute === void 0 ? {} : { substitute: rawSubstitute }
+	};
+}
+function isEnvNameStart(character) {
+	return /[A-Za-z_]/u.test(character);
+}
+function isEnvNamePart(character) {
+	return /[A-Za-z0-9_]/u.test(character);
+}
+function getLineNumber(input, offset) {
+	let line = 1;
+	for (let index = 0; index < offset; index++) if (input[index] === "\n") line++;
+	else if (input[index] === "\r") {
+		line++;
+		if (input[index + 1] === "\n") index++;
+	}
+	return line;
+}
+function syntaxError(path, line, messageText) {
+	return /* @__PURE__ */ new SyntaxError(`Invalid .env syntax in ${path} at line ${line}: ${messageText}.`);
+}
+function skipLine(input, index) {
+	while (index < input.length && input[index] !== "\r" && input[index] !== "\n") index++;
+	return index;
+}
+function readNewline(input, index) {
+	if (input[index] === "\r" && input[index + 1] === "\n") return index + 2;
+	if (input[index] === "\r") return index + 1;
+	if (input[index] === "\n") return index + 1;
+	return index;
+}
+function skipHorizontalWhitespace(input, index) {
+	while (input[index] === " " || input[index] === "	") index++;
+	return index;
+}
+function expandEnvValue(rawValue, lookup, substitute, options) {
+	let output = "";
+	for (let index = 0; index < rawValue.length; index++) {
+		const character = rawValue[index];
+		if (options.interpretEscapes && character === "\\") {
+			const next = rawValue[++index];
+			if (next === void 0) output += "\\";
+			else if (next === "n") output += "\n";
+			else if (next === "r") output += "\r";
+			else if (next === "t") output += "	";
+			else output += next;
+			continue;
+		}
+		if (!options.allowSubstitution) {
+			output += character;
+			continue;
+		}
+		if (character === "`") {
+			const end$1 = rawValue.indexOf("`", index + 1);
+			if (end$1 < 0) throw syntaxError(options.path, options.startLine, "unterminated command substitution");
+			const command = rawValue.slice(index + 1, end$1);
+			output += substitute?.(command) ?? "";
+			index = end$1;
+			continue;
+		}
+		if (character !== "$") {
+			output += character;
+			continue;
+		}
+		if (rawValue[index + 1] === "(") {
+			const end$1 = rawValue.indexOf(")", index + 2);
+			if (end$1 < 0) throw syntaxError(options.path, options.startLine, "unterminated command substitution");
+			const command = rawValue.slice(index + 2, end$1);
+			output += substitute?.(command) ?? "";
+			index = end$1;
+			continue;
+		}
+		if (rawValue[index + 1] === "{") {
+			const end$1 = rawValue.indexOf("}", index + 2);
+			if (end$1 < 0) throw syntaxError(options.path, options.startLine, "unterminated variable expansion");
+			const key$1 = rawValue.slice(index + 2, end$1);
+			output += lookup(key$1) ?? "";
+			index = end$1;
+			continue;
+		}
+		const nameStart = rawValue[index + 1];
+		if (nameStart === void 0 || !isEnvNameStart(nameStart)) {
+			output += character;
+			continue;
+		}
+		let end = index + 2;
+		while (end < rawValue.length && isEnvNamePart(rawValue[end])) end++;
+		const key = rawValue.slice(index + 1, end);
+		output += lookup(key) ?? "";
+		index = end - 1;
+	}
+	return output;
+}
+function parseQuotedEnvValue(input, index, quote, path, line, lookup, substitute) {
+	const valueStart = index + 1;
+	let cursor = valueStart;
+	while (cursor < input.length) {
+		const character = input[cursor];
+		if (character === "\\" && quote === "\"") {
+			cursor += 2;
+			continue;
+		}
+		if (character === quote) {
+			const rawValue = input.slice(valueStart, cursor);
+			const nextIndex = cursor + 1;
+			return {
+				value: quote === "'" ? rawValue : expandEnvValue(rawValue, lookup, substitute, {
+					path,
+					startLine: line,
+					interpretEscapes: true,
+					allowSubstitution: true
+				}),
+				nextIndex
+			};
+		}
+		cursor++;
+	}
+	throw syntaxError(path, line, "unterminated quoted value");
+}
+function parseUnquotedEnvValue(input, index, path, line, lookup, substitute) {
+	let cursor = index;
+	while (cursor < input.length && input[cursor] !== "\r" && input[cursor] !== "\n") {
+		if (input[cursor] === "#" && (cursor === index || /\s/u.test(input[cursor - 1]))) break;
+		cursor++;
+	}
+	const rawValue = input.slice(index, cursor).trimEnd();
+	return {
+		value: expandEnvValue(rawValue, lookup, substitute, {
+			path,
+			startLine: line,
+			interpretEscapes: false,
+			allowSubstitution: true
+		}),
+		nextIndex: cursor
+	};
+}
+function parseEnvFile(input, path, lookup, substitute, outerValues = /* @__PURE__ */ new Map()) {
+	const values = /* @__PURE__ */ new Map();
+	let index = input.charCodeAt(0) === 65279 ? 1 : 0;
+	while (index < input.length) {
+		const line = getLineNumber(input, index);
+		index = skipHorizontalWhitespace(input, index);
+		if (index >= input.length) break;
+		if (input[index] === "\r" || input[index] === "\n") {
+			index = readNewline(input, index);
+			continue;
+		}
+		if (input[index] === "#") {
+			index = readNewline(input, skipLine(input, index));
+			continue;
+		}
+		if (input.startsWith("export", index) && /\s/u.test(input[index + 6] ?? "")) index = skipHorizontalWhitespace(input, index + 6);
+		const keyStart = index;
+		if (!isEnvNameStart(input[index] ?? "")) throw syntaxError(path, line, "expected KEY=VALUE");
+		index++;
+		while (index < input.length && isEnvNamePart(input[index])) index++;
+		const key = input.slice(keyStart, index);
+		index = skipHorizontalWhitespace(input, index);
+		if (input[index] !== "=") throw syntaxError(path, line, "expected KEY=VALUE");
+		index = skipHorizontalWhitespace(input, index + 1);
+		const lineLookup = (lookupKey) => lookup(lookupKey) ?? values.get(lookupKey) ?? outerValues.get(lookupKey);
+		const parsed = input[index] === "'" || input[index] === "\"" ? parseQuotedEnvValue(input, index, input[index], path, line, lineLookup, substitute) : parseUnquotedEnvValue(input, index, path, line, lineLookup, substitute);
+		values.set(key, parsed.value);
+		index = skipHorizontalWhitespace(input, parsed.nextIndex);
+		if (input[index] === "#") index = skipLine(input, index);
+		else if (index < input.length && input[index] !== "\r" && input[index] !== "\n") throw syntaxError(path, line, "unexpected content after value");
+		index = readNewline(input, index);
+	}
+	return values;
+}
+function loadEnvFileValues(options, source) {
+	const values = /* @__PURE__ */ new Map();
+	for (const path of options.paths) {
+		const absolutePath = (0, node_path.resolve)(path);
+		try {
+			const contents = (0, node_fs.readFileSync)(absolutePath, "utf8");
+			const parsedValues = parseEnvFile(contents, absolutePath, source, options.substitute, values);
+			for (const [key, value] of parsedValues) values.set(key, value);
+		} catch (error) {
+			if (isErrnoException(error) && error.code === "ENOENT") continue;
+			throw error;
+		}
+	}
+	return values;
+}
 /**
 * Creates an environment context for use with Optique runners.
 *
@@ -54,16 +268,26 @@ function defaultEnvSource(key) {
 * @returns A context that provides environment source annotations.
 * @throws {TypeError} If `prefix` is not a string.
 * @throws {TypeError} If `source` is not a function.
+* @throws {TypeError} If `envFile` has an invalid shape.
+* @throws {SyntaxError} If an `.env` file contains invalid syntax.
+* @throws {Error} If an `.env` file cannot be read for a reason other than
+* a missing file.
 * @since 1.0.0
 */
 function createEnvContext(options = {}) {
 	const contextId = Symbol(`@optique/env context:${Math.random()}`);
 	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;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${getTypeName(rawSource)}.`);
+	const baseSource = 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}.`);
+	if (rawPrefix !== void 0 && typeof rawPrefix !== "string") throw new TypeError(`Expected prefix to be a string, but got: ${getTypeName(rawPrefix)}.`);
 	const prefix = rawPrefix ?? "";
+	const envFileOptions = normalizeEnvFileOptions(options.envFile);
+	const envFileValues = loadEnvFileValues(envFileOptions, baseSource);
+	const source = (key) => {
+		const value = baseSource(key);
+		return value === void 0 ? envFileValues.get(key) : value;
+	};
 	return {
 		id: contextId,
 		prefix,
@@ -124,6 +348,17 @@ function bindEnv(parser, options) {
 		return value != null && typeof value === "object" && envBindStateKey in value;
 	}
 	const deferPromptUntilConfigResolves = parser.shouldDeferCompletion;
+	function hasEnvFallback(state) {
+		if (options.default !== void 0) return true;
+		const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+		const sourceData = annotations?.[options.context.id];
+		if (sourceData == null) return false;
+		return sourceData.source(`${sourceData.prefix}${options.key}`) !== void 0;
+	}
+	function getInnerState(state) {
+		if (!isEnvBindState(state)) return state;
+		return state.cliState === void 0 ? (0, __optique_core_extension.inheritAnnotations)(state, parser.initialState) : state.cliState;
+	}
 	const boundParser = {
 		mode: parser.mode,
 		$valueType: parser.$valueType,
@@ -136,8 +371,17 @@ function bindEnv(parser, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
+		canSkip(state, exec) {
+			if (isEnvBindState(state)) {
+				if (state.hasCliValue) return parser.canSkip?.(state.cliState, exec) === true;
+				if (hasEnvFallback(state)) return true;
+				return parser.canSkip?.(getInnerState(state), exec) === true;
+			}
+			if (hasEnvFallback(state)) return true;
+			return parser.canSkip?.(state, exec) === true;
+		},
 		getSuggestRuntimeNodes(state, path) {
-			const innerState = isEnvBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+			const innerState = getInnerState(state);
 			return (0, __optique_core_extension.delegateSuggestNodes)(parser, boundParser, state, path, innerState);
 		},
 		parse: (context) => {

package/dist/index.d.cts

@@ -11,6 +11,37 @@ import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
  * @since 1.0.0
  */
 type EnvSource = (key: string) => string | undefined;
+/**
+ * Function type for command substitution in `.env` file values.
+ *
+ * @param command Command text captured from `$(...)` or backtick substitution.
+ * @returns Replacement text, or `undefined` to substitute an empty string.
+ * @since 1.1.0
+ */
+type EnvFileSubstitute = (command: string) => string | undefined;
+/**
+ * Path option for `.env` files loaded by {@link createEnvContext}.
+ *
+ * @since 1.1.0
+ */
+type EnvFilePaths = boolean | string | readonly string[];
+/**
+ * Options for loading `.env` files.
+ *
+ * @since 1.1.0
+ */
+interface EnvFileOptions {
+  /**
+   * Path or paths to `.env` files.  When `true` or omitted, loads `.env`
+   * from the current working directory.  Missing files are skipped.
+   */
+  readonly paths?: EnvFilePaths;
+  /**
+   * Optional command substitution hook for `$(...)` and backtick forms.
+   * Optique never executes commands by itself.
+   */
+  readonly substitute?: EnvFileSubstitute;
+}
 /**
  * Context for environment-variable-based fallback values.
  *
@@ -44,6 +75,20 @@ interface EnvContextOptions {
    * @default Runtime-specific source (`Deno.env.get` or `process.env`)
    */
   readonly source?: EnvSource;
+  /**
+   * Path(s) to `.env` files to load as an internal fallback layer.
+   *
+   * When `true`, searches for `.env` in the current working directory.
+   * When a string or array of strings, loads those explicit files.
+   * Files are loaded in order; later files override earlier files.
+   *
+   * Values loaded from `.env` files do not mutate `process.env` or
+   * `Deno.env`, and the real environment source remains higher priority.
+   *
+   * @default undefined
+   * @since 1.1.0
+   */
+  readonly envFile?: EnvFilePaths | EnvFileOptions;
 }
 /**
  * Creates an environment context for use with Optique runners.
@@ -66,6 +111,10 @@ interface EnvContextOptions {
  * @returns A context that provides environment source annotations.
  * @throws {TypeError} If `prefix` is not a string.
  * @throws {TypeError} If `source` is not a function.
+ * @throws {TypeError} If `envFile` has an invalid shape.
+ * @throws {SyntaxError} If an `.env` file contains invalid syntax.
+ * @throws {Error} If an `.env` file cannot be read for a reason other than
+ * a missing file.
  * @since 1.0.0
  */
 declare function createEnvContext(options?: EnvContextOptions): EnvContext;
@@ -172,4 +221,4 @@ interface BoolOptions {
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
 //#endregion
-export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, createEnvContext };
+export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvFileOptions, EnvFilePaths, EnvFileSubstitute, EnvSource, bindEnv, bool, createEnvContext };

package/dist/index.d.ts

@@ -11,6 +11,37 @@ import { Mode, Parser } from "@optique/core/parser";
  * @since 1.0.0
  */
 type EnvSource = (key: string) => string | undefined;
+/**
+ * Function type for command substitution in `.env` file values.
+ *
+ * @param command Command text captured from `$(...)` or backtick substitution.
+ * @returns Replacement text, or `undefined` to substitute an empty string.
+ * @since 1.1.0
+ */
+type EnvFileSubstitute = (command: string) => string | undefined;
+/**
+ * Path option for `.env` files loaded by {@link createEnvContext}.
+ *
+ * @since 1.1.0
+ */
+type EnvFilePaths = boolean | string | readonly string[];
+/**
+ * Options for loading `.env` files.
+ *
+ * @since 1.1.0
+ */
+interface EnvFileOptions {
+  /**
+   * Path or paths to `.env` files.  When `true` or omitted, loads `.env`
+   * from the current working directory.  Missing files are skipped.
+   */
+  readonly paths?: EnvFilePaths;
+  /**
+   * Optional command substitution hook for `$(...)` and backtick forms.
+   * Optique never executes commands by itself.
+   */
+  readonly substitute?: EnvFileSubstitute;
+}
 /**
  * Context for environment-variable-based fallback values.
  *
@@ -44,6 +75,20 @@ interface EnvContextOptions {
    * @default Runtime-specific source (`Deno.env.get` or `process.env`)
    */
   readonly source?: EnvSource;
+  /**
+   * Path(s) to `.env` files to load as an internal fallback layer.
+   *
+   * When `true`, searches for `.env` in the current working directory.
+   * When a string or array of strings, loads those explicit files.
+   * Files are loaded in order; later files override earlier files.
+   *
+   * Values loaded from `.env` files do not mutate `process.env` or
+   * `Deno.env`, and the real environment source remains higher priority.
+   *
+   * @default undefined
+   * @since 1.1.0
+   */
+  readonly envFile?: EnvFilePaths | EnvFileOptions;
 }
 /**
  * Creates an environment context for use with Optique runners.
@@ -66,6 +111,10 @@ interface EnvContextOptions {
  * @returns A context that provides environment source annotations.
  * @throws {TypeError} If `prefix` is not a string.
  * @throws {TypeError} If `source` is not a function.
+ * @throws {TypeError} If `envFile` has an invalid shape.
+ * @throws {SyntaxError} If an `.env` file contains invalid syntax.
+ * @throws {Error} If an `.env` file cannot be read for a reason other than
+ * a missing file.
  * @since 1.0.0
  */
 declare function createEnvContext(options?: EnvContextOptions): EnvContext;
@@ -172,4 +221,4 @@ interface BoolOptions {
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
 //#endregion
-export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvSource, bindEnv, bool, createEnvContext };
+export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvFileOptions, EnvFilePaths, EnvFileSubstitute, EnvSource, bindEnv, bool, createEnvContext };

package/dist/index.js

@@ -1,15 +1,229 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { getAnnotations } from "@optique/core/annotations";
-import { defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, wrapForMode } from "@optique/core/extension";
+import { defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, wrapForMode } from "@optique/core/extension";
 import { envVar, message, valueSet } from "@optique/core/message";
 import { ensureNonEmptyString, isValueParser } from "@optique/core/valueparser";
 
 //#region src/index.ts
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
 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];
 }
+function isErrnoException(error) {
+	return error != null && typeof error === "object" && "code" in error && typeof error.code === "string";
+}
+function normalizeEnvFilePaths(paths) {
+	if (paths === false) return [];
+	if (paths === true) return [".env"];
+	if (typeof paths === "string") return [paths];
+	if (Array.isArray(paths)) {
+		for (const path of paths) if (typeof path !== "string") throw new TypeError(`Expected envFile paths to be strings, but got: ${getTypeName(path)}.`);
+		return paths;
+	}
+	throw new TypeError(`Expected envFile.paths to be a boolean, string, array, or undefined, but got: ${getTypeName(paths)}.`);
+}
+function normalizeEnvFileOptions(envFile) {
+	if (envFile === void 0 || envFile === false) return { paths: [] };
+	if (envFile === true || typeof envFile === "string" || Array.isArray(envFile)) return { paths: normalizeEnvFilePaths(envFile) };
+	if (envFile == null || typeof envFile !== "object") throw new TypeError(`Expected envFile to be a boolean, string, array, or object, but got: ${getTypeName(envFile)}.`);
+	const options = envFile;
+	const rawSubstitute = options.substitute;
+	if (rawSubstitute !== void 0 && typeof rawSubstitute !== "function") throw new TypeError(`Expected envFile.substitute to be a function or undefined, but got: ${getTypeName(rawSubstitute)}.`);
+	return {
+		paths: normalizeEnvFilePaths(options.paths ?? true),
+		...rawSubstitute === void 0 ? {} : { substitute: rawSubstitute }
+	};
+}
+function isEnvNameStart(character) {
+	return /[A-Za-z_]/u.test(character);
+}
+function isEnvNamePart(character) {
+	return /[A-Za-z0-9_]/u.test(character);
+}
+function getLineNumber(input, offset) {
+	let line = 1;
+	for (let index = 0; index < offset; index++) if (input[index] === "\n") line++;
+	else if (input[index] === "\r") {
+		line++;
+		if (input[index + 1] === "\n") index++;
+	}
+	return line;
+}
+function syntaxError(path, line, messageText) {
+	return /* @__PURE__ */ new SyntaxError(`Invalid .env syntax in ${path} at line ${line}: ${messageText}.`);
+}
+function skipLine(input, index) {
+	while (index < input.length && input[index] !== "\r" && input[index] !== "\n") index++;
+	return index;
+}
+function readNewline(input, index) {
+	if (input[index] === "\r" && input[index + 1] === "\n") return index + 2;
+	if (input[index] === "\r") return index + 1;
+	if (input[index] === "\n") return index + 1;
+	return index;
+}
+function skipHorizontalWhitespace(input, index) {
+	while (input[index] === " " || input[index] === "	") index++;
+	return index;
+}
+function expandEnvValue(rawValue, lookup, substitute, options) {
+	let output = "";
+	for (let index = 0; index < rawValue.length; index++) {
+		const character = rawValue[index];
+		if (options.interpretEscapes && character === "\\") {
+			const next = rawValue[++index];
+			if (next === void 0) output += "\\";
+			else if (next === "n") output += "\n";
+			else if (next === "r") output += "\r";
+			else if (next === "t") output += "	";
+			else output += next;
+			continue;
+		}
+		if (!options.allowSubstitution) {
+			output += character;
+			continue;
+		}
+		if (character === "`") {
+			const end$1 = rawValue.indexOf("`", index + 1);
+			if (end$1 < 0) throw syntaxError(options.path, options.startLine, "unterminated command substitution");
+			const command = rawValue.slice(index + 1, end$1);
+			output += substitute?.(command) ?? "";
+			index = end$1;
+			continue;
+		}
+		if (character !== "$") {
+			output += character;
+			continue;
+		}
+		if (rawValue[index + 1] === "(") {
+			const end$1 = rawValue.indexOf(")", index + 2);
+			if (end$1 < 0) throw syntaxError(options.path, options.startLine, "unterminated command substitution");
+			const command = rawValue.slice(index + 2, end$1);
+			output += substitute?.(command) ?? "";
+			index = end$1;
+			continue;
+		}
+		if (rawValue[index + 1] === "{") {
+			const end$1 = rawValue.indexOf("}", index + 2);
+			if (end$1 < 0) throw syntaxError(options.path, options.startLine, "unterminated variable expansion");
+			const key$1 = rawValue.slice(index + 2, end$1);
+			output += lookup(key$1) ?? "";
+			index = end$1;
+			continue;
+		}
+		const nameStart = rawValue[index + 1];
+		if (nameStart === void 0 || !isEnvNameStart(nameStart)) {
+			output += character;
+			continue;
+		}
+		let end = index + 2;
+		while (end < rawValue.length && isEnvNamePart(rawValue[end])) end++;
+		const key = rawValue.slice(index + 1, end);
+		output += lookup(key) ?? "";
+		index = end - 1;
+	}
+	return output;
+}
+function parseQuotedEnvValue(input, index, quote, path, line, lookup, substitute) {
+	const valueStart = index + 1;
+	let cursor = valueStart;
+	while (cursor < input.length) {
+		const character = input[cursor];
+		if (character === "\\" && quote === "\"") {
+			cursor += 2;
+			continue;
+		}
+		if (character === quote) {
+			const rawValue = input.slice(valueStart, cursor);
+			const nextIndex = cursor + 1;
+			return {
+				value: quote === "'" ? rawValue : expandEnvValue(rawValue, lookup, substitute, {
+					path,
+					startLine: line,
+					interpretEscapes: true,
+					allowSubstitution: true
+				}),
+				nextIndex
+			};
+		}
+		cursor++;
+	}
+	throw syntaxError(path, line, "unterminated quoted value");
+}
+function parseUnquotedEnvValue(input, index, path, line, lookup, substitute) {
+	let cursor = index;
+	while (cursor < input.length && input[cursor] !== "\r" && input[cursor] !== "\n") {
+		if (input[cursor] === "#" && (cursor === index || /\s/u.test(input[cursor - 1]))) break;
+		cursor++;
+	}
+	const rawValue = input.slice(index, cursor).trimEnd();
+	return {
+		value: expandEnvValue(rawValue, lookup, substitute, {
+			path,
+			startLine: line,
+			interpretEscapes: false,
+			allowSubstitution: true
+		}),
+		nextIndex: cursor
+	};
+}
+function parseEnvFile(input, path, lookup, substitute, outerValues = /* @__PURE__ */ new Map()) {
+	const values = /* @__PURE__ */ new Map();
+	let index = input.charCodeAt(0) === 65279 ? 1 : 0;
+	while (index < input.length) {
+		const line = getLineNumber(input, index);
+		index = skipHorizontalWhitespace(input, index);
+		if (index >= input.length) break;
+		if (input[index] === "\r" || input[index] === "\n") {
+			index = readNewline(input, index);
+			continue;
+		}
+		if (input[index] === "#") {
+			index = readNewline(input, skipLine(input, index));
+			continue;
+		}
+		if (input.startsWith("export", index) && /\s/u.test(input[index + 6] ?? "")) index = skipHorizontalWhitespace(input, index + 6);
+		const keyStart = index;
+		if (!isEnvNameStart(input[index] ?? "")) throw syntaxError(path, line, "expected KEY=VALUE");
+		index++;
+		while (index < input.length && isEnvNamePart(input[index])) index++;
+		const key = input.slice(keyStart, index);
+		index = skipHorizontalWhitespace(input, index);
+		if (input[index] !== "=") throw syntaxError(path, line, "expected KEY=VALUE");
+		index = skipHorizontalWhitespace(input, index + 1);
+		const lineLookup = (lookupKey) => lookup(lookupKey) ?? values.get(lookupKey) ?? outerValues.get(lookupKey);
+		const parsed = input[index] === "'" || input[index] === "\"" ? parseQuotedEnvValue(input, index, input[index], path, line, lineLookup, substitute) : parseUnquotedEnvValue(input, index, path, line, lineLookup, substitute);
+		values.set(key, parsed.value);
+		index = skipHorizontalWhitespace(input, parsed.nextIndex);
+		if (input[index] === "#") index = skipLine(input, index);
+		else if (index < input.length && input[index] !== "\r" && input[index] !== "\n") throw syntaxError(path, line, "unexpected content after value");
+		index = readNewline(input, index);
+	}
+	return values;
+}
+function loadEnvFileValues(options, source) {
+	const values = /* @__PURE__ */ new Map();
+	for (const path of options.paths) {
+		const absolutePath = resolve(path);
+		try {
+			const contents = readFileSync(absolutePath, "utf8");
+			const parsedValues = parseEnvFile(contents, absolutePath, source, options.substitute, values);
+			for (const [key, value] of parsedValues) values.set(key, value);
+		} catch (error) {
+			if (isErrnoException(error) && error.code === "ENOENT") continue;
+			throw error;
+		}
+	}
+	return values;
+}
 /**
 * Creates an environment context for use with Optique runners.
 *
@@ -31,16 +245,26 @@ function defaultEnvSource(key) {
 * @returns A context that provides environment source annotations.
 * @throws {TypeError} If `prefix` is not a string.
 * @throws {TypeError} If `source` is not a function.
+* @throws {TypeError} If `envFile` has an invalid shape.
+* @throws {SyntaxError} If an `.env` file contains invalid syntax.
+* @throws {Error} If an `.env` file cannot be read for a reason other than
+* a missing file.
 * @since 1.0.0
 */
 function createEnvContext(options = {}) {
 	const contextId = Symbol(`@optique/env context:${Math.random()}`);
 	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;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${getTypeName(rawSource)}.`);
+	const baseSource = 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}.`);
+	if (rawPrefix !== void 0 && typeof rawPrefix !== "string") throw new TypeError(`Expected prefix to be a string, but got: ${getTypeName(rawPrefix)}.`);
 	const prefix = rawPrefix ?? "";
+	const envFileOptions = normalizeEnvFileOptions(options.envFile);
+	const envFileValues = loadEnvFileValues(envFileOptions, baseSource);
+	const source = (key) => {
+		const value = baseSource(key);
+		return value === void 0 ? envFileValues.get(key) : value;
+	};
 	return {
 		id: contextId,
 		prefix,
@@ -101,6 +325,17 @@ function bindEnv(parser, options) {
 		return value != null && typeof value === "object" && envBindStateKey in value;
 	}
 	const deferPromptUntilConfigResolves = parser.shouldDeferCompletion;
+	function hasEnvFallback(state) {
+		if (options.default !== void 0) return true;
+		const annotations = getAnnotations(state);
+		const sourceData = annotations?.[options.context.id];
+		if (sourceData == null) return false;
+		return sourceData.source(`${sourceData.prefix}${options.key}`) !== void 0;
+	}
+	function getInnerState(state) {
+		if (!isEnvBindState(state)) return state;
+		return state.cliState === void 0 ? inheritAnnotations(state, parser.initialState) : state.cliState;
+	}
 	const boundParser = {
 		mode: parser.mode,
 		$valueType: parser.$valueType,
@@ -113,8 +348,17 @@ function bindEnv(parser, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
+		canSkip(state, exec) {
+			if (isEnvBindState(state)) {
+				if (state.hasCliValue) return parser.canSkip?.(state.cliState, exec) === true;
+				if (hasEnvFallback(state)) return true;
+				return parser.canSkip?.(getInnerState(state), exec) === true;
+			}
+			if (hasEnvFallback(state)) return true;
+			return parser.canSkip?.(state, exec) === true;
+		},
 		getSuggestRuntimeNodes(state, path) {
-			const innerState = isEnvBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+			const innerState = getInnerState(state);
 			return delegateSuggestNodes(parser, boundParser, state, path, innerState);
 		},
 		parse: (context) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.1.0-dev.2087",
+  "version": "1.1.0-dev.2146",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -52,22 +52,29 @@
       "require": "./dist/index.cjs"
     }
   },
+  "imports": {
+    "#src/*.ts": {
+      "node": "./dist/*.js",
+      "default": "./src/*.ts"
+    }
+  },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.1.0-dev.2087+a3bd6720"
+    "@optique/core": "1.1.0-dev.2146+5fd0a75e"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "@optique/config": "1.1.0-dev.2146+5fd0a75e"
   },
   "scripts": {
     "build": "tsdown",
     "prepublish": "tsdown",
-    "test": "node --experimental-transform-types --test",
+    "test": "node --test",
     "test:bun": "bun test",
-    "test:deno": "deno test",
-    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+    "test:deno": "deno test --allow-read --allow-write --allow-env",
+    "test-all": "tsdown && node --test && bun test && deno test --allow-read --allow-write --allow-env"
   }
 }