@karmaniverous/get-dotenv 6.4.0 → 6.5.0

package/dist/chunks/{index-OeNCYa8T.mjs → index-jLjEQoIi.mjs}

@@ -1,19 +1,21 @@
 import { parse } from 'url';
 import { Buffer } from 'buffer';
 import { request } from 'http';
-import { aq as ProviderError, C as CredentialsProviderError, F as parseUrl, O as loadConfig } from './index-70Dm0f1N.mjs';
-import './readMergedOptions-B7VdLROn.mjs';
+import { aq as ProviderError, C as CredentialsProviderError, F as parseUrl, O as loadConfig } from './index-BCVlyd0W.mjs';
+import './readMergedOptions-DLRFU2qO.mjs';
 import 'zod';
 import '@commander-js/extra-typings';
-import './readDotenvCascade-DfFkWMjs.mjs';
+import './readDotenvCascade-Bymjvyit.mjs';
 import 'fs-extra';
+import 'radash';
+import 'node:buffer';
 import 'node:path';
 import './loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import 'path';
 import 'dotenv';
 import 'nanoid';
-import './loader-CePOf74i.mjs';
+import './loader-CE4HSRN4.mjs';
 import 'package-directory';
 import 'yaml';
 import 'execa';

package/dist/chunks/{loadSso-CLR1fKci.mjs → loadSso-BnjVSVhE.mjs}

@@ -1,10 +1,12 @@
-import { w as resolveAwsSdkSigV4Config, x as normalizeProvider, y as getSmithyContext, z as EndpointCache, A as resolveEndpoint, B as awsEndpointFunctions, D as customEndpointFunctions, t as toUtf8, i as fromUtf8, F as parseUrl, G as NoOpLogger, I as AwsSdkSigV4Signer, J as NoAuthSigner, n as toBase64, m as fromBase64, K as emitWarningIfUnsupportedVersion, L as resolveDefaultsModeConfig, M as emitWarningIfUnsupportedVersion$1, O as loadConfig, r as streamCollector, P as Hash, N as NodeHttpHandler, Q as createDefaultUserAgentProvider, R as calculateBodyLength, S as NODE_APP_ID_CONFIG_OPTIONS, T as NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS, U as NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS, V as NODE_RETRY_MODE_CONFIG_OPTIONS, W as DEFAULT_RETRY_MODE, X as NODE_REGION_CONFIG_FILE_OPTIONS, Y as NODE_REGION_CONFIG_OPTIONS, Z as NODE_MAX_ATTEMPT_CONFIG_OPTIONS, _ as NODE_AUTH_SCHEME_PREFERENCE_OPTIONS, $ as loadConfigsForDefaultMode, a0 as getAwsRegionExtensionConfiguration, a1 as getDefaultExtensionConfiguration, a2 as getHttpHandlerExtensionConfiguration, a3 as resolveAwsRegionExtensionConfiguration, a4 as resolveDefaultRuntimeConfig, a5 as resolveHttpHandlerRuntimeConfig, a6 as Client, a7 as resolveUserAgentConfig, a8 as resolveRetryConfig, a9 as resolveRegionConfig, aa as resolveEndpointConfig, ab as resolveHostHeaderConfig, ac as getSchemaSerdePlugin, ad as getUserAgentPlugin, ae as getRetryPlugin, af as getContentLengthPlugin, ag as getHostHeaderPlugin, ah as getLoggerPlugin, ai as getRecursionDetectionPlugin, aj as getHttpAuthSchemeEndpointRuleSetPlugin, ak as DefaultIdentityProviderConfig, al as getHttpSigningPlugin, am as ServiceException, an as TypeRegistry, ao as Command, ap as getEndpointPlugin } from './index-70Dm0f1N.mjs';
-import { A as AwsRestJsonProtocol } from './AwsRestJsonProtocol-fYZqn-kW.mjs';
-import './readMergedOptions-B7VdLROn.mjs';
+import { w as resolveAwsSdkSigV4Config, x as normalizeProvider, y as getSmithyContext, z as EndpointCache, A as resolveEndpoint, B as awsEndpointFunctions, D as customEndpointFunctions, t as toUtf8, i as fromUtf8, F as parseUrl, G as NoOpLogger, I as AwsSdkSigV4Signer, J as NoAuthSigner, n as toBase64, m as fromBase64, K as emitWarningIfUnsupportedVersion, L as resolveDefaultsModeConfig, M as emitWarningIfUnsupportedVersion$1, O as loadConfig, r as streamCollector, P as Hash, N as NodeHttpHandler, Q as createDefaultUserAgentProvider, R as calculateBodyLength, S as NODE_APP_ID_CONFIG_OPTIONS, T as NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS, U as NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS, V as NODE_RETRY_MODE_CONFIG_OPTIONS, W as DEFAULT_RETRY_MODE, X as NODE_REGION_CONFIG_FILE_OPTIONS, Y as NODE_REGION_CONFIG_OPTIONS, Z as NODE_MAX_ATTEMPT_CONFIG_OPTIONS, _ as NODE_AUTH_SCHEME_PREFERENCE_OPTIONS, $ as loadConfigsForDefaultMode, a0 as getAwsRegionExtensionConfiguration, a1 as getDefaultExtensionConfiguration, a2 as getHttpHandlerExtensionConfiguration, a3 as resolveAwsRegionExtensionConfiguration, a4 as resolveDefaultRuntimeConfig, a5 as resolveHttpHandlerRuntimeConfig, a6 as Client, a7 as resolveUserAgentConfig, a8 as resolveRetryConfig, a9 as resolveRegionConfig, aa as resolveEndpointConfig, ab as resolveHostHeaderConfig, ac as getSchemaSerdePlugin, ad as getUserAgentPlugin, ae as getRetryPlugin, af as getContentLengthPlugin, ag as getHostHeaderPlugin, ah as getLoggerPlugin, ai as getRecursionDetectionPlugin, aj as getHttpAuthSchemeEndpointRuleSetPlugin, ak as DefaultIdentityProviderConfig, al as getHttpSigningPlugin, am as ServiceException, an as TypeRegistry, ao as Command, ap as getEndpointPlugin } from './index-BCVlyd0W.mjs';
+import { A as AwsRestJsonProtocol } from './AwsRestJsonProtocol-D_GDWyaH.mjs';
+import './readMergedOptions-DLRFU2qO.mjs';
 import 'zod';
 import '@commander-js/extra-typings';
-import './readDotenvCascade-DfFkWMjs.mjs';
+import './readDotenvCascade-Bymjvyit.mjs';
 import 'fs-extra';
+import 'radash';
+import 'node:buffer';
 import 'node:path';
 import './loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
@@ -12,7 +14,7 @@ import 'path';
 import 'url';
 import 'dotenv';
 import 'nanoid';
-import './loader-CePOf74i.mjs';
+import './loader-CE4HSRN4.mjs';
 import 'package-directory';
 import 'yaml';
 import 'execa';
@@ -24,7 +26,7 @@ import 'https';
 import 'stream';
 import 'process';
 import 'node:fs';
-import './sdk-stream-mixin-ecbbBR0l.mjs';
+import './sdk-stream-mixin-BDitDomf.mjs';
 
 const defaultSSOHttpAuthSchemeParametersProvider = async (config, context, input) => {
     return {

package/dist/chunks/{loader-CePOf74i.mjs → loader-CE4HSRN4.mjs}

@@ -4,8 +4,11 @@ import path, { join, extname } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import YAML from 'yaml';
 import { z } from 'zod';
+import 'radash';
+import 'node:buffer';
 import 'node:path';
 import { l as loadModuleDefault } from './loadModuleDefault-Dj8B3Stt.mjs';
+import '@commander-js/extra-typings';
 
 /**
  * Zod schemas for programmatic GetDotenv options.

package/dist/chunks/{parseKnownFiles-BQvmJ0HK.mjs → parseKnownFiles-CejYPe7q.mjs}

@@ -1,4 +1,4 @@
-import { l as loadSharedConfigFiles } from './index-70Dm0f1N.mjs';
+import { l as loadSharedConfigFiles } from './index-BCVlyd0W.mjs';
 
 const mergeConfigFiles = (...files) => {
     const merged = {};

package/dist/chunks/{readDotenvCascade-DfFkWMjs.mjs → readDotenvCascade-Bymjvyit.mjs}

@@ -1,6 +1,9 @@
 import fs from 'fs-extra';
+import 'radash';
+import 'node:buffer';
 import path from 'node:path';
 import { l as loadModuleDefault } from './loadModuleDefault-Dj8B3Stt.mjs';
+import '@commander-js/extra-typings';
 import { parse } from 'dotenv';
 import 'crypto';
 import 'path';
@@ -118,7 +121,7 @@ const dotenvExpand = (value, ref = process.env) => {
  * subsequent expansions in the same object (left-to-right by object key order).
  */
 function dotenvExpandAll(values, options = {}) {
-    const { ref = process.env, progressive = false, } = options;
+    const { ref = process.env, progressive = false } = options;
     const out = Object.keys(values).reduce((acc, key) => {
         acc[key] = dotenvExpand(values[key], {
             ...ref,

package/dist/chunks/{readMergedOptions-B7VdLROn.mjs → readMergedOptions-DLRFU2qO.mjs}

@@ -1,20 +1,30 @@
 import { z } from 'zod';
 import { Option, Command } from '@commander-js/extra-typings';
-import { g as dotenvExpand, r as readDotenvCascadeWithProvenance, o as overlayEnvWithProvenance, b as applyDynamicMapWithProvenance, l as loadDynamicModuleDefault, h as dotenvExpandFromProcessEnv } from './readDotenvCascade-DfFkWMjs.mjs';
+import { g as dotenvExpand, r as readDotenvCascadeWithProvenance, o as overlayEnvWithProvenance, b as applyDynamicMapWithProvenance, l as loadDynamicModuleDefault, h as dotenvExpandFromProcessEnv } from './readDotenvCascade-Bymjvyit.mjs';
 import fs from 'fs-extra';
 import 'node:path';
 import 'nanoid';
 import path from 'path';
+import { isObject, shake } from 'radash';
+import 'node:buffer';
 import 'crypto';
 import { fileURLToPath } from 'url';
 import 'dotenv';
-import { g as getDotenvOptionsSchemaResolved, r as resolveGetDotenvConfigSources } from './loader-CePOf74i.mjs';
+import { g as getDotenvOptionsSchemaResolved, r as resolveGetDotenvConfigSources } from './loader-CE4HSRN4.mjs';
 import { packageDirectory } from 'package-directory';
 
+/**
+ * Plain-object deep merge with "later overrides earlier" semantics.
+ * - Only merges plain objects (prototype === Object.prototype).
+ * - Arrays and non-objects are replaced, not concatenated or merged.
+ * - Undefined values are ignored (do not overwrite).
+ *
+ * Merge order: defaultsDeep(base, override1, override2) → override2 wins.
+ */
 /** @internal */
-const isPlainObject$1 = (value) => value !== null &&
-    typeof value === 'object' &&
-    Object.getPrototypeOf(value) === Object.prototype;
+const isPlainObject$1 = (value) => {
+    return isObject(value) && !Array.isArray(value);
+};
 const mergeInto = (target, source) => {
     for (const [key, sVal] of Object.entries(source)) {
         if (sVal === undefined)
@@ -57,11 +67,20 @@ async function writeDotenvFile(filename, data) {
     await fs.writeFile(filename, body, { encoding: 'utf-8' });
 }
 
+/**
+ * Deep interpolation utility for string leaves.
+ * - Expands string values using dotenv-style expansion against the provided envRef.
+ * - Preserves non-strings as-is.
+ * - Does not recurse into arrays (arrays are returned unchanged).
+ *
+ * Intended for:
+ * - Phase C option/config interpolation after composing ctx.dotenv.
+ * - Per-plugin config slice interpolation before afterResolve.
+ */
 /** @internal */
-const isPlainObject = (v) => v !== null &&
-    typeof v === 'object' &&
-    !Array.isArray(v) &&
-    Object.getPrototypeOf(v) === Object.prototype;
+const isPlainObject = (v) => {
+    return isObject(v) && !Array.isArray(v);
+};
 /**
  * Deeply interpolate string leaves against envRef.
  * Arrays are not recursed into; they are returned unchanged.
@@ -103,33 +122,6 @@ const interpolateDeep = (value, envRef) => {
     return value;
 };
 
-/** src/util/omitUndefined.ts
- * Helpers to drop undefined-valued properties in a typed-friendly way.
- */
-/**
- * Omit keys whose runtime value is undefined from a shallow object.
- * Returns a Partial with non-undefined value types preserved.
- *
- * @typeParam T - Input object shape.
- * @param obj - Object to filter.
- * @returns A shallow copy of `obj` without keys whose value is `undefined`.
- */
-/**
- * Specialized helper for env-like maps: drop undefined and return string-only.
- *
- * @typeParam V - Value type for present entries (must extend `string`).
- * @param obj - Env-like record containing `string | undefined` values.
- * @returns A new record containing only the keys with defined values.
- */
-function omitUndefinedRecord(obj) {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        if (v !== undefined)
-            out[k] = v;
-    }
-    return out;
-}
-
 /**
  * Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
  * Used as the bottom layer for CLI option resolution.
@@ -171,6 +163,16 @@ const baseRootOptionDefaults = {
     // (debug/log/exclude* resolved via flag utils)
 };
 
+// src/GetDotenvOptions.ts
+/**
+ * Canonical programmatic options and helpers for get-dotenv.
+ *
+ * Requirements addressed:
+ * - GetDotenvOptions derives from the Zod schema output (single source of truth).
+ * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
+ * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
+ * - Preserve existing behavior for defaults resolution and compat converters.
+ */
 function defineDynamic(d) {
     return d;
 }
@@ -230,7 +232,7 @@ debug: _debug, scripts: _scripts, ...rest }) => {
     // Drop undefined-valued entries at the converter stage to match ProcessEnv
     // expectations and the compat test assertions.
     if (parsedVars) {
-        parsedVars = omitUndefinedRecord(parsedVars);
+        parsedVars = shake(parsedVars, (v) => v === undefined);
     }
     // Tolerate paths as either a delimited string or string[]
     const pathsOut = Array.isArray(paths)
@@ -266,7 +268,7 @@ const resolveGetDotenvOptions = (customOptions) => {
     const result = defaultsDeep(defaultsFromCli, customOptions);
     return Promise.resolve({
         ...result, // Keep explicit empty strings/zeros; drop only undefined
-        vars: omitUndefinedRecord(result.vars ?? {}),
+        vars: shake(result.vars ?? {}, (v) => v === undefined),
     });
 };
 

package/dist/chunks/{resolveCliOptions-pgUXHJtj.mjs → resolveCliOptions-C6oeNl9S.mjs}

@@ -1,9 +1,12 @@
-import { b as baseRootOptionDefaults, a as defaultsDeep } from './readMergedOptions-B7VdLROn.mjs';
+import { b as baseRootOptionDefaults, a as defaultsDeep } from './readMergedOptions-DLRFU2qO.mjs';
+import 'radash';
+import 'node:buffer';
 import 'fs-extra';
 import 'node:path';
 import 'crypto';
 import 'path';
 import 'url';
+import '@commander-js/extra-typings';
 
 /**
  * Base CLI options derived from the shared root option defaults.

package/dist/chunks/{sdk-stream-mixin-ecbbBR0l.mjs → sdk-stream-mixin-BDitDomf.mjs}

@@ -1,4 +1,4 @@
-import { m as fromBase64, n as toBase64, o as toHex, t as toUtf8, q as fromArrayBuffer, r as streamCollector$1 } from './index-70Dm0f1N.mjs';
+import { m as fromBase64, n as toBase64, o as toHex, t as toUtf8, q as fromArrayBuffer, r as streamCollector$1 } from './index-BCVlyd0W.mjs';
 import { Readable } from 'stream';
 
 const isReadableStream = (stream) => typeof ReadableStream === "function" &&

package/dist/chunks/{spawnEnv-CQwFu7ZJ.mjs → spawnEnv-5kdIVv0x.mjs}

@@ -1,9 +1,12 @@
 import { execa, execaCommand } from 'execa';
+import { shake } from 'radash';
+import 'node:buffer';
 import 'fs-extra';
 import 'node:path';
 import 'crypto';
 import 'path';
 import 'url';
+import '@commander-js/extra-typings';
 
 /**
  * Minimal tokenizer for shell-off execution.
@@ -255,7 +258,6 @@ const resolveShell = (scripts, command, shell) => scripts && typeof scripts[comm
     ? (scripts[command].shell ?? false)
     : (shell ?? false);
 
-const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
 /**
  * Build a sanitized environment object for spawning child processes.
  * Merges `base` and `overlay`, drops undefined values, and handles platform-specific
@@ -270,7 +272,8 @@ const buildSpawnEnv = (base, overlay) => {
         ...(overlay ?? {}),
     };
     // Drop undefined first
-    const entries = Object.entries(dropUndefined(raw));
+    const clean = shake(raw, (v) => v === undefined);
+    const entries = Object.entries(clean);
     if (process.platform === 'win32') {
         // Windows: keys are case-insensitive; collapse duplicates
         const byLower = new Map();

package/dist/chunks/{types-CVDR-Sjk.mjs → types-BC96rfQj.mjs}

@@ -1,4 +1,4 @@
-import { d as definePlugin } from './readMergedOptions-B7VdLROn.mjs';
+import { d as definePlugin } from './readMergedOptions-DLRFU2qO.mjs';
 
 /**
  * Create a namespace-only parent plugin (a group command) for composing plugins

package/dist/cli.d.ts

@@ -360,16 +360,6 @@ interface BrandOptions {
     helpHeader?: string;
 }
 
-/**
- * Canonical programmatic options and helpers for get-dotenv.
- *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
- */
-
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset".

package/dist/cli.mjs

@@ -1,26 +1,28 @@
-export { c as createCli } from './chunks/createCli-BnRdfRRL.mjs';
+export { c as createCli } from './chunks/createCli-Ct22WCEC.mjs';
 import 'zod';
 import 'path';
-import './chunks/loader-CePOf74i.mjs';
+import './chunks/loader-CE4HSRN4.mjs';
 import 'fs-extra';
 import 'package-directory';
 import 'url';
 import 'yaml';
+import 'radash';
+import 'node:buffer';
 import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
-import 'nanoid';
-import './chunks/readMergedOptions-B7VdLROn.mjs';
 import '@commander-js/extra-typings';
-import './chunks/readDotenvCascade-DfFkWMjs.mjs';
+import 'nanoid';
+import './chunks/readMergedOptions-DLRFU2qO.mjs';
+import './chunks/readDotenvCascade-Bymjvyit.mjs';
 import 'dotenv';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-pgUXHJtj.mjs';
+import './chunks/resolveCliOptions-C6oeNl9S.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
-import './chunks/spawnEnv-CQwFu7ZJ.mjs';
-import './chunks/index-70Dm0f1N.mjs';
+import './chunks/spawnEnv-5kdIVv0x.mjs';
+import './chunks/index-BCVlyd0W.mjs';
 import 'buffer';
 import 'os';
 import 'node:fs/promises';
@@ -32,7 +34,7 @@ import 'node:fs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
-import './chunks/index-r0Me7-sT.mjs';
+import './chunks/index-BzOeGJbq.mjs';
 import './plugins-init.mjs';
 import 'node:process';
 import 'readline/promises';

package/dist/cliHost.d.ts

@@ -366,16 +366,6 @@ interface BrandOptions {
     helpHeader?: string;
 }
 
-/**
- * Canonical programmatic options and helpers for get-dotenv.
- *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
- */
-
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset".
@@ -654,6 +644,16 @@ declare function definePlugin<TOptions extends GetDotenvOptions, Schema extends
 }): PluginWithInstanceHelpers<TOptions, z.output<Schema>>;
 declare function definePlugin<TOptions extends GetDotenvOptions>(spec: DefineSpec<TOptions>): PluginWithInstanceHelpers<TOptions, {}>;
 
+/**
+ * Non-interactive confirm guard for destructive ops.
+ * Returns true when force is provided; otherwise warns and sets exitCode.
+ *
+ * @param force - The force flag value (truthy allows proceed).
+ * @param op - Operation name for the warning message.
+ * @param flag - The flag name to suggest in the warning message (default: '--force').
+ */
+declare function ensureForce(force: unknown, op: string, flag?: string): boolean;
+
 /**
  * Helper to decide whether to capture child stdio.
  * Checks GETDOTENV_STDIO env var or the provided bag capture flag.
@@ -959,6 +959,33 @@ interface GroupPluginsOptions<TOptions extends GetDotenvOptions = GetDotenvOptio
  */
 declare function groupPlugins<TOptions extends GetDotenvOptions = GetDotenvOptions>(options: GroupPluginsOptions<TOptions>): PluginWithInstanceHelpers<TOptions, {}>;
 
+/**
+ * Return type for {@link describeConfigKeyListDefaults}.
+ *
+ * @public
+ */
+interface DescribeConfigKeyListDefaultsResult {
+    /** Description for the include list default. */
+    includeDefault: string;
+    /** Description for the exclude list default. */
+    excludeDefault: string;
+}
+/**
+ * Describe a default value for help text.
+ * Handles arrays (joins with space) and strings; returns 'none' if empty/undefined.
+ */
+declare const describeDefault: (v: unknown) => string;
+/**
+ * Describe default values for a pair of include/exclude list options.
+ * Returns an object with `includeDefault` and `excludeDefault` strings.
+ *
+ * If both lists are populated, returns an invalid marker for both.
+ */
+declare const describeConfigKeyListDefaults: ({ cfgInclude, cfgExclude, }: {
+    cfgInclude?: string[];
+    cfgExclude?: string[];
+}) => DescribeConfigKeyListDefaultsResult;
+
 /** src/cliHost/invoke.ts
  * Shared helpers for composing child env overlays and preserving argv for Node -e.
  */
@@ -971,7 +998,7 @@ declare function groupPlugins<TOptions extends GetDotenvOptions = GetDotenvOptio
  * @param dotenv - Composed dotenv variables for the current invocation.
  * @returns A string-only env overlay suitable for child process spawning.
  */
-declare function composeNestedEnv(merged: GetDotenvCliOptions | Record<string, unknown>, dotenv: Record<string, string | undefined>): Record<string, string>;
+declare function composeNestedEnv(merged: GetDotenvCliOptions | Record<string, unknown>, dotenv: ProcessEnv): Record<string, string>;
 /**
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
@@ -1086,7 +1113,7 @@ declare const resolveCliOptions: <T extends ResolveCliOptionsShape>(rawCliOption
  * @param base - Base environment (usually `process.env`).
  * @param overlay - Environment variables to overlay.
  */
-declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => NodeJS.ProcessEnv;
+declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: ProcessEnv) => NodeJS.ProcessEnv;
 
-export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, groupPlugins, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
+export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, describeConfigKeyListDefaults, describeDefault, ensureForce, getRootCommand, groupPlugins, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
 export type { BrandOptions, DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GroupPluginsOptions, InferPluginConfig, PluginChildEntry, PluginFlattenedEntry, PluginNamespaceOverride, PluginWithInstanceHelpers, ResolveAndLoadOptions, ResolveCliOptionsResult, ResolvedHelpConfig, RootOptionsShape, RunCommandOptions, RunCommandResultOptions, ScriptDef, Scripts, ScriptsTable };

package/dist/cliHost.mjs

@@ -1,13 +1,15 @@
-export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-B7VdLROn.mjs';
-export { d as buildSpawnEnv, b as resolveCommand, c as resolveShell, r as runCommand, a as runCommandResult, s as shouldCapture } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
-export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-pgUXHJtj.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-CVDR-Sjk.mjs';
+export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-DLRFU2qO.mjs';
+export { d as buildSpawnEnv, b as resolveCommand, c as resolveShell, r as runCommand, a as runCommandResult, s as shouldCapture } from './chunks/spawnEnv-5kdIVv0x.mjs';
+export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-C6oeNl9S.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-BC96rfQj.mjs';
 export { t as toHelpConfig } from './chunks/helpConfig-CGejgwWW.mjs';
 export { c as composeNestedEnv, m as maybePreserveNodeEvalArgv, s as stripOne } from './chunks/invoke-DuRPU1oC.mjs';
 export { z } from 'zod';
 import '@commander-js/extra-typings';
-import './chunks/readDotenvCascade-DfFkWMjs.mjs';
+import './chunks/readDotenvCascade-Bymjvyit.mjs';
 import 'fs-extra';
+import 'radash';
+import 'node:buffer';
 import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
@@ -15,11 +17,27 @@ import 'path';
 import 'url';
 import 'dotenv';
 import 'nanoid';
-import './chunks/loader-CePOf74i.mjs';
+import './chunks/loader-CE4HSRN4.mjs';
 import 'package-directory';
 import 'yaml';
 import 'execa';
 
+/**
+ * Non-interactive confirm guard for destructive ops.
+ * Returns true when force is provided; otherwise warns and sets exitCode.
+ *
+ * @param force - The force flag value (truthy allows proceed).
+ * @param op - Operation name for the warning message.
+ * @param flag - The flag name to suggest in the warning message (default: '--force').
+ */
+function ensureForce(force, op, flag = '--force') {
+    if (force)
+        return true;
+    console.warn(`${op} requires confirmation. Re-run with ${flag} to proceed.`);
+    process.exitCode = 2;
+    return false;
+}
+
 /**
  * Return the top-level root command for a given mount or action's thisCommand.
  *
@@ -33,4 +51,33 @@ const getRootCommand = (cmd) => {
     return node;
 };
 
-export { getRootCommand };
+/**
+ * Describe a default value for help text.
+ * Handles arrays (joins with space) and strings; returns 'none' if empty/undefined.
+ */
+const describeDefault = (v) => {
+    if (Array.isArray(v))
+        return v.length ? v.join(' ') : 'none';
+    if (typeof v === 'string' && v.trim())
+        return v;
+    return 'none';
+};
+/**
+ * Describe default values for a pair of include/exclude list options.
+ * Returns an object with `includeDefault` and `excludeDefault` strings.
+ *
+ * If both lists are populated, returns an invalid marker for both.
+ */
+const describeConfigKeyListDefaults = ({ cfgInclude, cfgExclude, }) => {
+    // Avoid throwing in help rendering: show an explicit invalid marker.
+    if (cfgInclude?.length && cfgExclude?.length) {
+        const msg = '(invalid: both set in config)';
+        return { includeDefault: msg, excludeDefault: msg };
+    }
+    return {
+        includeDefault: describeDefault(cfgExclude?.length ? undefined : cfgInclude),
+        excludeDefault: describeDefault(cfgInclude?.length ? undefined : cfgExclude),
+    };
+};
+
+export { describeConfigKeyListDefaults, describeDefault, ensureForce, getRootCommand };

package/dist/config.d.ts

@@ -99,16 +99,6 @@ interface ScriptDef<TShell extends string | boolean = string | boolean> {
  */
 type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
 
-/**
- * Canonical programmatic options and helpers for get-dotenv.
- *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
- */
-
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset".

package/dist/config.mjs

@@ -1,4 +1,4 @@
-export { d as discoverConfigFiles, l as loadConfigFile, r as resolveGetDotenvConfigSources, t as toFileUrl } from './chunks/loader-CePOf74i.mjs';
+export { d as discoverConfigFiles, l as loadConfigFile, r as resolveGetDotenvConfigSources, t as toFileUrl } from './chunks/loader-CE4HSRN4.mjs';
 export { v as validateEnvAgainstSources } from './chunks/validate-CDl0rE6k.mjs';
 import 'fs-extra';
 import 'package-directory';
@@ -6,6 +6,9 @@ import 'path';
 import 'url';
 import 'yaml';
 import 'zod';
+import 'radash';
+import 'node:buffer';
 import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
+import '@commander-js/extra-typings';

package/dist/env-overlay.d.ts

@@ -153,16 +153,6 @@ type GetDotenvConfigResolved = {
     plugins?: Record<string, unknown>;
 };
 
-/**
- * Canonical programmatic options and helpers for get-dotenv.
- *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
- */
-
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset".
@@ -411,7 +401,7 @@ type OverlayConfigSources = {
  * @typeParam B - base env shape
  * @public
  */
-interface OverlayEnvOptionsBase<B extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>> {
+interface OverlayEnvOptionsBase<B extends ProcessEnv | Readonly<ProcessEnv>> {
     /** Base environment variables. */
     base: B;
     /** Target environment name. */
@@ -426,7 +416,7 @@ interface OverlayEnvOptionsBase<B extends Record<string, string | undefined> | R
  * @typeParam P - programmatic vars shape
  * @public
  */
-interface OverlayEnvOptionsWithProgrammatic<B extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>, P extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>> extends OverlayEnvOptionsBase<B> {
+interface OverlayEnvOptionsWithProgrammatic<B extends ProcessEnv | Readonly<ProcessEnv>, P extends ProcessEnv | Readonly<ProcessEnv>> extends OverlayEnvOptionsBase<B> {
     /**
      * Explicit programmatic variables applied at the highest precedence tier.
      */
@@ -441,12 +431,12 @@ interface OverlayEnvOptionsWithProgrammatic<B extends Record<string, string | un
  * Programmatic explicit vars (if provided) override all config slices.
  * Progressive expansion is applied within each slice.
  */
-declare function overlayEnv<B extends ProcessEnv | Readonly<Record<string, string | undefined>>>(args: {
+declare function overlayEnv<B extends ProcessEnv | Readonly<ProcessEnv>>(args: {
     base: B;
     env: string | undefined;
     configs: OverlayConfigSources;
 }): B;
-declare function overlayEnv<B extends ProcessEnv | Readonly<Record<string, string | undefined>>, P extends ProcessEnv | Readonly<Record<string, string | undefined>>>(args: {
+declare function overlayEnv<B extends ProcessEnv | Readonly<ProcessEnv>, P extends ProcessEnv | Readonly<ProcessEnv>>(args: {
     base: B;
     env: string | undefined;
     configs: OverlayConfigSources;
@@ -472,7 +462,7 @@ interface OverlayEnvWithProvenanceArgs {
     /**
      * Base environment variables.
      */
-    base: ProcessEnv | Readonly<Record<string, string | undefined>>;
+    base: ProcessEnv | Readonly<ProcessEnv>;
     /**
      * Target environment name.
      */
@@ -484,7 +474,7 @@ interface OverlayEnvWithProvenanceArgs {
     /**
      * Explicit vars overlays applied at the highest static precedence tier.
      */
-    programmaticVars?: ProcessEnv | Readonly<Record<string, string | undefined>>;
+    programmaticVars?: ProcessEnv | Readonly<ProcessEnv>;
     /**
      * Existing provenance map to append into. When omitted, a new map is created.
      */

package/dist/env-overlay.mjs

@@ -1,11 +1,14 @@
-import { d as dotenvExpandAll } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
-export { a as applyDynamicMap, b as applyDynamicMapWithProvenance, e as createDotenvProvenance, c as loadAndApplyDynamic, l as loadDynamicModuleDefault, o as overlayEnvWithProvenance, p as pushDotenvProvenance, r as readDotenvCascadeWithProvenance } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
+import { d as dotenvExpandAll } from './chunks/readDotenvCascade-Bymjvyit.mjs';
+export { a as applyDynamicMap, b as applyDynamicMapWithProvenance, e as createDotenvProvenance, c as loadAndApplyDynamic, l as loadDynamicModuleDefault, o as overlayEnvWithProvenance, p as pushDotenvProvenance, r as readDotenvCascadeWithProvenance } from './chunks/readDotenvCascade-Bymjvyit.mjs';
 import 'fs-extra';
 import 'node:path';
+import 'radash';
+import 'node:buffer';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import 'path';
 import 'url';
+import '@commander-js/extra-typings';
 import 'dotenv';
 
 const applyKv = (current, kv) => {