@karmaniverous/get-dotenv 7.0.7 → 7.0.9

package/dist/chunks/{createCli-DRgcaM2D.mjs → createCli-CCxTLJ1j.mjs}

@@ -1,24 +1,24 @@
 import 'zod';
 import 'path';
-import { r as resolveGetDotenvConfigSources } from './loader-V1vbmtyw.mjs';
+import { r as resolveGetDotenvConfigSources } from './loader-C3DtD6HB.mjs';
 import 'nanoid';
 import 'fs-extra';
 import 'node:path';
 import 'radash';
 import 'node:buffer';
-import { d as defaultsDeep, h as getDotenvCliOptions2Options, c as baseRootOptionDefaults, G as GetDotenvCli, b as attachRootOptions } from './readMergedOptions-x80ltQO_.mjs';
+import { a as defaultsDeep, g as getDotenvCliOptions2Options, b as baseRootOptionDefaults, G as GetDotenvCli, c as attachRootOptions } from './readMergedOptions-_hjyCNZ7.mjs';
 import 'crypto';
 import 'url';
 import '@commander-js/extra-typings';
 import 'dotenv';
 import 'execa';
 import { t as toHelpConfig } from './helpConfig-CGejgwWW.mjs';
-import { r as resolveCliOptions } from './resolveCliOptions-CR-BEUmS.mjs';
+import { r as resolveCliOptions } from './resolveCliOptions-Dp7wPY1K.mjs';
 import { v as validateEnvAgainstSources } from './validate-CDl0rE6k.mjs';
 import { awsPlugin } from '../plugins-aws.mjs';
-import { R as awsWhoamiPlugin } from './index-4kbkrHS9.mjs';
+import { a as awsWhoamiPlugin } from './index-Cay5Gzhu.mjs';
 import { batchPlugin } from '../plugins-batch.mjs';
-import { c as cmdPlugin } from './index-BzoCat8h.mjs';
+import { c as cmdPlugin } from './index-xqvxTkr9.mjs';
 import { initPlugin } from '../plugins-init.mjs';
 
 const dbg = (...args) => {
@@ -66,7 +66,7 @@ function installRootHooks(program, defaults) {
         }
     };
     // Hook: preSubcommand — always runs for subcommand flows.
-    program.hook('preSubcommand', async (thisCommand, actionCommand) => {
+    program.hook('preSubcommand', async (thisCommand, _actionCommand) => {
         const sources = await resolveGetDotenvConfigSources(import.meta.url);
         const rawArgs = thisCommand.rawArgs ?? [];
         dbg('preSubcommand:rawArgs', rawArgs);
@@ -82,11 +82,16 @@ function installRootHooks(program, defaults) {
         thisCommand.getDotenvCliOptions = merged;
         program._setOptionsBag(merged);
         // Resolve context for this run via programmatic converter.
+        // afterResolve is deferred to preAction where the full command path is known.
         const serviceOptions = getDotenvCliOptions2Options(merged);
         await program.resolveAndLoad(serviceOptions, {
-            invokedSubcommand: actionCommand.name(),
+            runAfterResolve: false,
         });
         propagateResolvedEnv(merged);
+        // Propagate debug flag to env so dbg() helpers and error boundary see it.
+        if (merged.debug) {
+            process.env.GETDOTENV_DEBUG = '1';
+        }
         // Refresh dynamic help text using the resolved config slices.
         try {
             const ctx = program.getCtx();
@@ -115,8 +120,8 @@ function installRootHooks(program, defaults) {
             /* tolerate non-strict flows */
         }
     });
-    // Hook: preAction — root-only and parent-alias flows.
-    program.hook('preAction', async (thisCommand) => {
+    // Hook: preAction — root-only and parent-alias flows + scoped afterResolve.
+    program.hook('preAction', async (thisCommand, actionCommand) => {
         const sources = await resolveGetDotenvConfigSources(import.meta.url);
         const rawArgs = thisCommand.rawArgs ?? [];
         dbg('preAction:rawArgs', rawArgs);
@@ -139,6 +144,10 @@ function installRootHooks(program, defaults) {
         // builds a fresh `merged` and overwrites the options bag, so the env
         // propagated by preSubcommand is lost without this call.
         propagateResolvedEnv(merged);
+        // Propagate debug flag to env so dbg() helpers and error boundary see it.
+        if (merged.debug) {
+            process.env.GETDOTENV_DEBUG = '1';
+        }
         try {
             const ctx = program.getCtx();
             const helpCfg = toHelpConfig(merged, ctx.pluginConfigs);
@@ -162,6 +171,20 @@ function installRootHooks(program, defaults) {
         catch {
             /* tolerate non-strict flows */
         }
+        // Run afterResolve scoped to the invoked command branch.
+        // Walk actionCommand.parent chain to build the full plugin path.
+        // Always true after resolution above, but satisfies the type checker.
+        const ctx = program.hasCtx() ? program.getCtx() : undefined;
+        if (ctx) {
+            const segments = [];
+            let node = actionCommand;
+            while (node && node !== thisCommand) {
+                segments.unshift(node.name());
+                node = node
+                    .parent;
+            }
+            await program._runAfterResolve(ctx, segments.length > 0 ? segments : undefined);
+        }
     });
     return program;
 }
@@ -258,6 +281,25 @@ function applyRootVisibility(program, visibility) {
     }
 }
 
+/**
+ * Top-level error boundary for the CLI runner.
+ *
+ * Presents errors as clean one-line messages by default.
+ * When GETDOTENV_DEBUG is set, prints the full stack trace.
+ */
+function handleCliError(err, argv) {
+    const isDebug = process.env.GETDOTENV_DEBUG === '1' ||
+        process.env.GETDOTENV_DEBUG === 'true' ||
+        (Array.isArray(argv) && argv.includes('--debug'));
+    const message = err instanceof Error ? err.message : String(err);
+    if (isDebug) {
+        console.error(err instanceof Error ? (err.stack ?? message) : message);
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exitCode = 1;
+}
 /**
  * Create a configured get-dotenv CLI host.
  * Applies defaults, installs root hooks, and composes plugins.
@@ -453,7 +495,12 @@ function createCli(opts = {}) {
                 ? { helpHeader: opts.branding }
                 : {}),
         });
-        await program.parseAsync(['node', alias, ...argv]);
+        try {
+            await program.parseAsync(['node', alias, ...argv]);
+        }
+        catch (err) {
+            handleCliError(err, argv);
+        }
     };
 }
 

package/dist/chunks/index-Cay5Gzhu.mjs

@@ -0,0 +1,111 @@
+import { d as definePlugin } from './readMergedOptions-_hjyCNZ7.mjs';
+import 'execa';
+import 'radash';
+import 'node:buffer';
+import 'fs-extra';
+import 'node:path';
+import 'crypto';
+import 'path';
+import 'url';
+import '@commander-js/extra-typings';
+import 'nanoid';
+import 'dotenv';
+import './loader-C3DtD6HB.mjs';
+import 'package-directory';
+import 'yaml';
+import 'zod';
+
+/**
+ * Attach the default action for the `aws whoami` command.
+ *
+ * This behavior executes only when `aws whoami` is invoked without a subcommand.
+ *
+ * @param cli - The `whoami` command mount.
+ * @returns Nothing.
+ */
+function attachWhoamiDefaultAction(cli) {
+    cli.action(async () => {
+        // Dynamic import: @aws-sdk/client-sts is an optional peer dependency.
+        // A static import would cause Node to fail at startup (even for -h)
+        // when the SDK is not installed in the consumer's project.
+        let GetCallerIdentityCommand;
+        let STSClient;
+        try {
+            const mod = await import('@aws-sdk/client-sts');
+            GetCallerIdentityCommand = mod.GetCallerIdentityCommand;
+            STSClient = mod.STSClient;
+        }
+        catch {
+            console.error('The aws whoami command requires @aws-sdk/client-sts.\n' +
+                'Install it with: npm install @aws-sdk/client-sts');
+            process.exitCode = 1;
+            return;
+        }
+        // The AWS SDK default providers will read credentials from process.env,
+        // which the aws parent has already populated.
+        const client = new STSClient();
+        const result = await client.send(new GetCallerIdentityCommand());
+        console.log(JSON.stringify(result, null, 2));
+    });
+}
+
+/**
+ * Attach options/arguments for the `aws whoami` plugin mount.
+ *
+ * This subcommand currently takes no flags/args; this module exists to keep the
+ * wiring layout consistent across shipped plugins (options vs actions).
+ *
+ * Note: the plugin description is owned by `src/plugins/aws/whoami/index.ts` and
+ * must not be set here.
+ *
+ * @param cli - The `whoami` command mount under `aws`.
+ * @returns The same `cli` instance for chaining.
+ *
+ * @internal
+ */
+function attachWhoamiOptions(cli) {
+    return cli;
+}
+
+/**
+ * Attach the `really` subcommand under `aws whoami`.
+ *
+ * Reads `SECRET_IDENTITY` from the resolved get-dotenv context (`cli.getCtx().dotenv`).
+ *
+ * @param cli - The `whoami` command mount.
+ * @returns Nothing.
+ */
+function attachWhoamiReallyAction(cli) {
+    const really = cli
+        .ns('really')
+        .description('Print SECRET_IDENTITY from the resolved dotenv context');
+    really.action(() => {
+        const secretIdentity = really.getCtx().dotenv.SECRET_IDENTITY;
+        console.log(`Your secret identity is ${secretIdentity ?? 'still a secret'}.`);
+    });
+}
+
+/**
+ * AWS Whoami plugin factory.
+ *
+ * This plugin demonstrates a “bucket of subcommands” pattern:
+ * - Subcommand behavior is articulated in separate modules as `attach*` helpers.
+ * - Those helpers are not individually composable plugins; they are internal wiring for one plugin instance.
+ *
+ * @returns A plugin instance mounted at `aws whoami`.
+ */
+const awsWhoamiPlugin = () => definePlugin({
+    ns: 'whoami',
+    setup(cli) {
+        cli.description('Print AWS caller identity (uses parent aws session)');
+        // Options/args (none today, but keep layout consistent with other plugins).
+        const whoami = attachWhoamiOptions(cli);
+        // Default behavior: `getdotenv aws whoami`
+        attachWhoamiDefaultAction(whoami);
+        // Subcommand behavior: `getdotenv aws whoami really`
+        attachWhoamiReallyAction(whoami);
+        return undefined;
+    },
+});
+
+export { awsWhoamiPlugin as a };

package/dist/chunks/{index-BzoCat8h.mjs → index-xqvxTkr9.mjs}

@@ -1,5 +1,5 @@
 import { camel } from 'radash';
-import { r as readMergedOptions, d as defaultsDeep, h as getDotenvCliOptions2Options, g as definePlugin } from './readMergedOptions-x80ltQO_.mjs';
+import { r as readMergedOptions, a as defaultsDeep, g as getDotenvCliOptions2Options, d as definePlugin } from './readMergedOptions-_hjyCNZ7.mjs';
 import 'execa';
 import 'node:buffer';
 import 'fs-extra';
@@ -10,14 +10,14 @@ import 'url';
 import '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import { r as resolveGetDotenvConfigSources } from './loader-V1vbmtyw.mjs';
+import { r as resolveGetDotenvConfigSources } from './loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import { z } from 'zod';
-import { r as resolveCommand, a as resolveShell, t as tokenize, s as shouldCapture, c as runCommand, b as buildSpawnEnv } from './spawnEnv-CKgnHGpr.mjs';
+import { r as resolveCommand, a as resolveShell, t as tokenize, s as shouldCapture, c as runCommand, b as buildSpawnEnv } from './spawnEnv-DvisqPiU.mjs';
 import { m as maybePreserveNodeEvalArgv, c as composeNestedEnv, s as stripOne } from './invoke-DuRPU1oC.mjs';
-import { f as dotenvExpandFromProcessEnv } from './readDotenvCascade-Dgx4SC1p.mjs';
-import { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './resolveCliOptions-CR-BEUmS.mjs';
+import { f as dotenvExpandFromProcessEnv } from './readDotenvCascade-CfFPgLCp.mjs';
+import { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './resolveCliOptions-Dp7wPY1K.mjs';
 
 /** src/diagnostics/entropy.ts
  * Entropy diagnostics (presentation-only).
@@ -480,4 +480,4 @@ const cmdPlugin = (options = {}) => {
     return plugin;
 };
 
-export { redactObject as a, cmdPlugin as c, maybeWarnEntropy as m, redactDisplay as r, traceChildEnv as t };
+export { redactDisplay as a, cmdPlugin as c, maybeWarnEntropy as m, redactObject as r, traceChildEnv as t };

package/dist/chunks/{loader-V1vbmtyw.mjs → loader-C3DtD6HB.mjs}

@@ -288,7 +288,7 @@ const discoverConfigFiles = async (importMetaUrl) => {
  * For JS/TS: default export is loaded; "dynamic" is allowed.
  */
 const loadConfigFile = async (filePath) => {
-    let raw = {};
+    let raw;
     try {
         const abs = path.resolve(filePath);
         if (isJsOrTs(abs)) {
@@ -302,7 +302,9 @@ const loadConfigFile = async (filePath) => {
         }
     }
     catch (err) {
-        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
+        throw new Error(`Failed to read/parse config: ${filePath}.`, {
+            cause: err,
+        });
     }
     // Validate RAW
     const parsed = getDotenvConfigSchemaRaw.safeParse(raw);

package/dist/chunks/{readDotenvCascade-Dgx4SC1p.mjs → readDotenvCascade-CfFPgLCp.mjs}

@@ -189,21 +189,31 @@ function pushDotenvProvenance(prov, key, entry) {
  */
 /**
  * Apply a dynamic map to the target progressively.
- * - Functions receive (target, env) and may return string | undefined.
- * - Literals are assigned directly (including undefined).
+ * - Functions receive (target, env) and may return string | null | undefined.
+ * - string → set the key to that value.
+ * - undefined → no-op, leave existing value unchanged.
+ * - null → delete the key from the target.
  *
  * @param target - Mutable target environment to assign into.
  * @param map - Dynamic map to apply (functions and/or literal values).
  * @param env - Selected environment name (if any) passed through to dynamic functions.
- * @returns Nothing.
+ * @returns Set of keys that were deleted (value was null).
  */
 function applyDynamicMap(target, map, env) {
+    const deleted = new Set();
     if (!map)
-        return;
+        return deleted;
     for (const key of Object.keys(map)) {
         const val = typeof map[key] === 'function' ? map[key](target, env) : map[key];
-        Object.assign(target, { [key]: val });
+        if (val === null) {
+            Reflect.deleteProperty(target, key);
+            deleted.add(key);
+        }
+        else if (val !== undefined)
+            target[key] = val;
+        // undefined → no-op
     }
+    return deleted;
 }
 /**
  * Load a default-export dynamic map from a JS/TS file (without applying it).
@@ -245,25 +255,46 @@ async function loadDynamicModuleDefault(absPath, cacheDirName) {
  * @param prov - Provenance map to append into.
  * @param meta - Dynamic provenance metadata (source tier and optional dynamicPath).
  *
+ * @returns Set of keys that were deleted (value was null).
+ *
  * @public
  */
 function applyDynamicMapWithProvenance(target, map, env, prov, meta) {
+    const deleted = new Set();
     if (!map)
-        return;
+        return deleted;
     for (const key of Object.keys(map)) {
         const val = typeof map[key] === 'function' ? map[key](target, env) : map[key];
-        Object.assign(target, { [key]: val });
-        pushDotenvProvenance(prov, key, {
-            kind: 'dynamic',
-            op: typeof val === 'string' ? 'set' : 'unset',
-            dynamicSource: meta.dynamicSource,
-            ...(meta.dynamicSource === 'dynamicPath' &&
-                typeof meta.dynamicPath === 'string' &&
-                meta.dynamicPath.length > 0
-                ? { dynamicPath: meta.dynamicPath }
-                : {}),
-        });
+        if (val === null) {
+            Reflect.deleteProperty(target, key);
+            deleted.add(key);
+            pushDotenvProvenance(prov, key, {
+                kind: 'dynamic',
+                op: 'unset',
+                dynamicSource: meta.dynamicSource,
+                ...(meta.dynamicSource === 'dynamicPath' &&
+                    typeof meta.dynamicPath === 'string' &&
+                    meta.dynamicPath.length > 0
+                    ? { dynamicPath: meta.dynamicPath }
+                    : {}),
+            });
+        }
+        else if (val !== undefined) {
+            target[key] = val;
+            pushDotenvProvenance(prov, key, {
+                kind: 'dynamic',
+                op: 'set',
+                dynamicSource: meta.dynamicSource,
+                ...(meta.dynamicSource === 'dynamicPath' &&
+                    typeof meta.dynamicPath === 'string' &&
+                    meta.dynamicPath.length > 0
+                    ? { dynamicPath: meta.dynamicPath }
+                    : {}),
+            });
+        }
+        // undefined → no-op, no provenance entry
     }
+    return deleted;
 }
 /**
  * Load a default-export dynamic map from a JS/TS file and apply it.
@@ -278,13 +309,13 @@ function applyDynamicMapWithProvenance(target, map, env, prov, meta) {
  * @param absPath - Absolute path to the dynamic module file.
  * @param env - Selected environment name (if any).
  * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
- * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
+ * @returns A `Promise\<Set\<string\>\>` resolving to the set of deleted keys.
  */
 async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
     const dyn = await loadDynamicModuleDefault(absPath, cacheDirName);
     if (!dyn)
-        return;
-    applyDynamicMap(target, dyn, env);
+        return new Set();
+    return applyDynamicMap(target, dyn, env);
 }
 
 /**
@@ -542,4 +573,4 @@ async function readDotenvCascadeWithProvenance(args) {
     return { dotenv: expanded, provenance: prov };
 }
 
-export { applyDynamicMap as a, applyDynamicMapWithProvenance as b, createDotenvProvenance as c, dotenvExpand as d, dotenvExpandAll as e, dotenvExpandFromProcessEnv as f, loadDynamicModuleDefault as g, readDotenvCascadeWithProvenance as h, loadAndApplyDynamic as l, overlayEnvWithProvenance as o, pushDotenvProvenance as p, readDotenv as r };
+export { applyDynamicMap as a, applyDynamicMapWithProvenance as b, createDotenvProvenance as c, dotenvExpandAll as d, loadDynamicModuleDefault as e, dotenvExpandFromProcessEnv as f, readDotenv as g, dotenvExpand as h, loadAndApplyDynamic as l, overlayEnvWithProvenance as o, pushDotenvProvenance as p, readDotenvCascadeWithProvenance as r };

package/dist/chunks/{readMergedOptions-x80ltQO_.mjs → readMergedOptions-_hjyCNZ7.mjs}

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { Option, Command } from '@commander-js/extra-typings';
-import { d as dotenvExpand, h as readDotenvCascadeWithProvenance, o as overlayEnvWithProvenance, b as applyDynamicMapWithProvenance, g as loadDynamicModuleDefault, f as dotenvExpandFromProcessEnv } from './readDotenvCascade-Dgx4SC1p.mjs';
+import { h as dotenvExpand, r as readDotenvCascadeWithProvenance, o as overlayEnvWithProvenance, b as applyDynamicMapWithProvenance, e as loadDynamicModuleDefault, f as dotenvExpandFromProcessEnv } from './readDotenvCascade-CfFPgLCp.mjs';
 import fs from 'fs-extra';
 import 'node:path';
 import 'nanoid';
@@ -10,7 +10,7 @@ import 'node:buffer';
 import 'crypto';
 import { fileURLToPath } from 'url';
 import 'dotenv';
-import { g as getDotenvOptionsSchemaResolved, r as resolveGetDotenvConfigSources } from './loader-V1vbmtyw.mjs';
+import { g as getDotenvOptionsSchemaResolved, r as resolveGetDotenvConfigSources } from './loader-C3DtD6HB.mjs';
 import { packageDirectory } from 'package-directory';
 
 /**
@@ -737,6 +737,19 @@ const attachRootOptions = (program, defaults) => {
         program.addOption(lf);
         program.setOptionGroup(lf, GROUP);
     }
+    // Debug ON/OFF (dynamic)
+    {
+        const dOn = program
+            .createDynamicOption('--debug', (cfg) => `enable debug logging to stderr ${onOff(true, Boolean(cfg.debug))}`)
+            .conflicts('debugOff');
+        program.addOption(dOn);
+        program.setOptionGroup(dOn, GROUP);
+        const dOff = program
+            .createDynamicOption('--debug-off', (cfg) => `enable debug logging to stderr ${onOff(false, !cfg.debug)}`)
+            .conflicts('debug');
+        program.addOption(dOff);
+        program.setOptionGroup(dOff, GROUP);
+    }
     // Capture flag (no default display; static)
     {
         const opt = new Option('--capture', 'capture child process stdio for commands (tests/CI)');
@@ -947,7 +960,7 @@ function buildHelpInformation(base, cmd) {
     }
     const marker = '\nCommands:';
     const idx = base.indexOf(marker);
-    let out = base;
+    let out;
     if (idx >= 0) {
         const toInsert = groups.startsWith('\n') ? groups : `\n${groups}`;
         out = `${base.slice(0, idx)}${toInsert}${base.slice(idx)}`;
@@ -1278,7 +1291,10 @@ class GetDotenvCli extends Command {
         // Ensure plugins are installed exactly once, then run afterResolve.
         await this.install();
         if (opts?.runAfterResolve ?? true) {
-            await this._runAfterResolve(ctx, opts?.invokedSubcommand);
+            const path = opts?.invokedSubcommand
+                ? [opts.invokedSubcommand]
+                : undefined;
+            await this._runAfterResolve(ctx, path);
         }
         return ctx;
     }
@@ -1438,16 +1454,40 @@ class GetDotenvCli extends Command {
     }
     /**
      * Run afterResolve hooks for registered plugins (parent → children).
-     * When {@link invokedSubcommand} is provided, only the matching plugin
-     * subtree runs; otherwise all plugins run (backward compatibility).
+     * When {@link commandPath} is provided, only the matching branch of the
+     * plugin tree runs; otherwise all plugins run (backward compatibility).
+     *
+     * The path is walked segment-by-segment against the plugin tree.
+     * Intermediate matches run their own afterResolve hook.
+     * The deepest match runs afterResolve for itself and all its descendants.
      */
-    async _runAfterResolve(ctx, invokedSubcommand) {
-        const plugins = invokedSubcommand
-            ? this._plugins
-                .filter((e) => effectiveNs(e) === invokedSubcommand)
-                .map((e) => e.plugin)
-            : this._plugins.map((e) => e.plugin);
-        await runAfterResolveTree(this, plugins, ctx);
+    async _runAfterResolve(ctx, commandPath) {
+        if (!commandPath || commandPath.length === 0) {
+            await runAfterResolveTree(this, this._plugins.map((e) => e.plugin), ctx);
+            return;
+        }
+        // Walk the plugin tree along the command path, scoping to the invoked branch.
+        let entries = this._plugins;
+        for (let i = 0; i < commandPath.length; i++) {
+            const segment = commandPath[i];
+            const entry = entries.find((e) => effectiveNs(e) === segment);
+            if (!entry)
+                return;
+            const isLast = i === commandPath.length - 1;
+            const nextSegment = commandPath[i + 1];
+            const hasMatchingChild = !isLast &&
+                entry.plugin.children.some((e) => effectiveNs(e) === nextSegment);
+            if (isLast || !hasMatchingChild) {
+                // Deepest match: run this plugin + all its descendants.
+                await runAfterResolveTree(this, [entry.plugin], ctx);
+                return;
+            }
+            // Intermediate match: run only this plugin's own afterResolve.
+            if (entry.plugin.afterResolve) {
+                await entry.plugin.afterResolve(this, ctx);
+            }
+            entries = entry.plugin.children;
+        }
     }
 }
 
@@ -1477,4 +1517,4 @@ const readMergedOptions = (cmd) => {
     return bag;
 };
 
-export { GetDotenvCli as G, assertLogger as a, attachRootOptions as b, baseRootOptionDefaults as c, defaultsDeep as d, defineDynamic as e, defineGetDotenvConfig as f, definePlugin as g, getDotenvCliOptions2Options as h, interpolateDeep as i, resolveGetDotenvOptions as j, readMergedOptions as r, writeDotenvFile as w };
+export { GetDotenvCli as G, defaultsDeep as a, baseRootOptionDefaults as b, attachRootOptions as c, definePlugin as d, resolveGetDotenvOptions as e, assertLogger as f, getDotenvCliOptions2Options as g, defineDynamic as h, defineGetDotenvConfig as i, interpolateDeep as j, readMergedOptions as r, writeDotenvFile as w };

package/dist/chunks/{resolveCliOptions-CR-BEUmS.mjs → resolveCliOptions-Dp7wPY1K.mjs}

@@ -1,4 +1,4 @@
-import { c as baseRootOptionDefaults, d as defaultsDeep } from './readMergedOptions-x80ltQO_.mjs';
+import { b as baseRootOptionDefaults, a as defaultsDeep } from './readMergedOptions-_hjyCNZ7.mjs';
 import 'radash';
 import 'node:buffer';
 import 'fs-extra';

package/dist/chunks/{spawnEnv-CKgnHGpr.mjs → spawnEnv-DvisqPiU.mjs}

@@ -84,6 +84,26 @@ const shouldCapture = (bagCapture) => process.env.GETDOTENV_STDIO === 'pipe' ||
 // This is safe for argv arrays passed to execa (no quoting needed) and avoids
 // passing quote characters through to Node (e.g., for `node -e "<code>"`).
 // Handles stacked quotes from shells like PowerShell: """code""" -> code.
+// Shell-quote a single token for safe interpolation when joining an argv
+// array into a command string destined for a shell.  On Windows (cmd.exe)
+// wrap in double quotes when the token contains shell metacharacters; on
+// Unix wrap in single quotes with escaped embedded singles.
+const shellQuoteToken = (s) => {
+    if (process.platform === 'win32') {
+        // cmd.exe: double-quote tokens with special chars.  Inner double
+        // quotes are escaped with backslash (Node/libuv convention).
+        if (/[\s"'&|<>^()!%+,;=]/.test(s)) {
+            return '"' + s.replace(/"/g, '\\"') + '"';
+        }
+        return s;
+    }
+    // POSIX: single-quote tokens with special chars.  Embedded single
+    // quotes break out, add an escaped single, and re-enter.
+    if (/[\s"'&|<>()!$\\`~#;{}[\]*?+]/.test(s)) {
+        return "'" + s.replace(/'/g, "'\\''") + "'";
+    }
+    return s;
+};
 const stripOuterQuotes = (s) => {
     let out = s;
     // Repeatedly trim only when the entire string is wrapped in matching quotes.
@@ -129,7 +149,7 @@ async function _execNormalized(command, shell, opts = {}) {
     const stdio = opts.stdio ?? 'pipe';
     if (shell === false) {
         let file;
-        let args = [];
+        let args;
         if (typeof command === 'string') {
             const tokens = tokenize(command);
             file = tokens[0];
@@ -158,8 +178,13 @@ async function _execNormalized(command, shell, opts = {}) {
             return out;
         }
     }
-    // Shell path (string|true|URL): execaCommand handles shell resolution.
-    const commandStr = typeof command === 'string' ? command : command.join(' ');
+    // Shell path (string|true|URL): build a single command string for the
+    // target shell.  When the command is an array we shell-quote each token
+    // individually before joining so that metacharacters (spaces, quotes, +,
+    // parentheses, etc.) survive the round-trip through cmd.exe / sh.
+    const commandStr = typeof command === 'string'
+        ? command
+        : command.map(shellQuoteToken).join(' ');
     dbg('exec (shell)', {
         command: commandStr,
         shell: typeof shell === 'string' ? shell : 'custom',

package/dist/chunks/{types-poB1VAs_.mjs → types-zXDNhcST.mjs}

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

package/dist/cli.d.ts

@@ -286,7 +286,7 @@ interface RootOptionsShape {
      */
     trace?: boolean | string[];
     /** Paths to search for dotenv files (space-delimited string or array). */
-    paths?: string;
+    paths?: string | string[];
     /** Delimiter for paths string (default: space). */
     pathsDelimiter?: string;
     /** Regex pattern for paths delimiter. */
@@ -378,7 +378,7 @@ type ProcessEnv = Record<string, string | undefined>;
  * and the selected environment (if any), and returns either a string to set
  * or `undefined` to unset/skip the variable.
  */
-type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
 /**
  * A map of dynamic variable definitions.
  * Keys are variable names; values are either literal strings or functions.
@@ -713,10 +713,14 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
     install(): Promise<void>;
     /**
      * Run afterResolve hooks for registered plugins (parent → children).
-     * When {@link invokedSubcommand} is provided, only the matching plugin
-     * subtree runs; otherwise all plugins run (backward compatibility).
+     * When {@link commandPath} is provided, only the matching branch of the
+     * plugin tree runs; otherwise all plugins run (backward compatibility).
+     *
+     * The path is walked segment-by-segment against the plugin tree.
+     * Intermediate matches run their own afterResolve hook.
+     * The deepest match runs afterResolve for itself and all its descendants.
      */
-    private _runAfterResolve;
+    _runAfterResolve(ctx: GetDotenvCliCtx<TOptions>, commandPath?: string[]): Promise<void>;
 }
 
 /**