@karmaniverous/get-dotenv 7.0.6 → 7.0.8

package/dist/chunks/{createCli-BkHLeYXL.mjs → createCli-CUPiFVdZ.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-CraAnYdB.mjs';
+import { a as defaultsDeep, g as getDotenvCliOptions2Options, b as baseRootOptionDefaults, G as GetDotenvCli, c as attachRootOptions } from './readMergedOptions-BT1C87_u.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-BMBkWDYJ.mjs';
+import { r as resolveCliOptions } from './resolveCliOptions-BbfouWSK.mjs';
 import { v as validateEnvAgainstSources } from './validate-CDl0rE6k.mjs';
 import { awsPlugin } from '../plugins-aws.mjs';
-import { R as awsWhoamiPlugin } from './index-BuxEK_Z4.mjs';
+import { a as awsWhoamiPlugin } from './index-CNXekCQC.mjs';
 import { batchPlugin } from '../plugins-batch.mjs';
-import { c as cmdPlugin } from './index-Dd6S1nZ-.mjs';
+import { c as cmdPlugin } from './index-DnG3N6yj.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) => {
+    program.hook('preSubcommand', async (thisCommand, _actionCommand) => {
         const sources = await resolveGetDotenvConfigSources(import.meta.url);
         const rawArgs = thisCommand.rawArgs ?? [];
         dbg('preSubcommand:rawArgs', rawArgs);
@@ -82,8 +82,11 @@ 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);
+        await program.resolveAndLoad(serviceOptions, {
+            runAfterResolve: false,
+        });
         propagateResolvedEnv(merged);
         // Refresh dynamic help text using the resolved config slices.
         try {
@@ -113,8 +116,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);
@@ -130,7 +133,7 @@ function installRootHooks(program, defaults) {
         program._setOptionsBag(merged);
         if (!program.hasCtx()) {
             const serviceOptions = getDotenvCliOptions2Options(merged);
-            await program.resolveAndLoad(serviceOptions);
+            await program.resolveAndLoad(serviceOptions, { runAfterResolve: false });
         }
         // Always propagate resolved env into the merged bag — even when
         // preSubcommand already set the context.  preAction unconditionally
@@ -160,6 +163,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;
 }

package/dist/chunks/index-CNXekCQC.mjs

@@ -0,0 +1,96 @@
+import { d as definePlugin } from './readMergedOptions-BT1C87_u.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';
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+
+/**
+ * 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 () => {
+        // 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-Dd6S1nZ-.mjs → index-DnG3N6yj.mjs}

@@ -1,5 +1,5 @@
 import { camel } from 'radash';
-import { r as readMergedOptions, d as defaultsDeep, h as getDotenvCliOptions2Options, g as definePlugin } from './readMergedOptions-CraAnYdB.mjs';
+import { r as readMergedOptions, a as defaultsDeep, g as getDotenvCliOptions2Options, d as definePlugin } from './readMergedOptions-BT1C87_u.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-BMBkWDYJ.mjs';
+import { f as dotenvExpandFromProcessEnv } from './readDotenvCascade-CfFPgLCp.mjs';
+import { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './resolveCliOptions-BbfouWSK.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-CraAnYdB.mjs → readMergedOptions-BT1C87_u.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';
 
 /**
@@ -947,7 +947,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)}`;
@@ -1078,12 +1078,14 @@ function initializeInstance(cli, headerGetter) {
     cli.hook('preSubcommand', async () => {
         if (cli.hasCtx())
             return;
-        await cli.resolveAndLoad({ loadProcess: false });
+        await cli.resolveAndLoad({ loadProcess: false }, { runAfterResolve: false });
     });
 }
 
 /**
  * Determine the effective namespace for a child plugin (override \> default).
+ * Uses a structural parameter so any entry with `.override?.ns` and `.plugin.ns`
+ * is accepted regardless of full generic variance.
  */
 const effectiveNs = (child) => {
     const o = child.override;
@@ -1258,10 +1260,14 @@ class GetDotenvCli extends Command {
      * Resolve options (strict) and compute dotenv context.
      * Stores the context on the instance under a symbol.
      *
-     * Options:
-     * - opts.runAfterResolve (default true): when false, skips running plugin
-     *   afterResolve hooks. Useful for top-level help rendering to avoid
-     *   long-running side-effects while still evaluating dynamic help text.
+     * @param customOptions - Partial options to overlay for this invocation.
+     * @param opts - Optional resolver behavior switches.
+     *   - `runAfterResolve` (default `true`): when false, skips running plugin
+     *     afterResolve hooks. Useful for top-level help rendering to avoid
+     *     long-running side-effects while still evaluating dynamic help text.
+     *   - `invokedSubcommand`: when provided, only the plugin subtree whose
+     *     namespace matches this name runs afterResolve hooks. When omitted,
+     *     all plugins run afterResolve (backward compatibility).
      */
     async resolveAndLoad(customOptions = {}, opts) {
         const ctx = await resolveAndComputeContext(customOptions, 
@@ -1272,7 +1278,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);
+            const path = opts?.invokedSubcommand
+                ? [opts.invokedSubcommand]
+                : undefined;
+            await this._runAfterResolve(ctx, path);
         }
         return ctx;
     }
@@ -1431,10 +1440,41 @@ class GetDotenvCli extends Command {
         }
     }
     /**
-     * Run afterResolve hooks for all plugins (parent → children).
+     * Run afterResolve hooks for registered plugins (parent → children).
+     * 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) {
-        await runAfterResolveTree(this, this._plugins.map((e) => e.plugin), 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;
+        }
     }
 }
 
@@ -1464,4 +1504,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-BMBkWDYJ.mjs → resolveCliOptions-BbfouWSK.mjs}

@@ -1,4 +1,4 @@
-import { c as baseRootOptionDefaults, d as defaultsDeep } from './readMergedOptions-CraAnYdB.mjs';
+import { b as baseRootOptionDefaults, a as defaultsDeep } from './readMergedOptions-BT1C87_u.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-BthqmnDr.mjs → types-BkQxnyZK.mjs}

@@ -1,4 +1,4 @@
-import { g as definePlugin } from './readMergedOptions-CraAnYdB.mjs';
+import { d as definePlugin } from './readMergedOptions-BT1C87_u.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.
@@ -464,6 +464,12 @@ interface ResolveAndLoadOptions {
      * @default true
      */
     runAfterResolve?: boolean;
+    /**
+     * Name of the invoked subcommand (plugin namespace). When provided,
+     * only the matching plugin subtree runs afterResolve hooks.
+     * When omitted, all plugins run afterResolve (backward compatibility).
+     */
+    invokedSubcommand?: string;
 }
 /**
  * Structural public interface for the host exposed to plugins.
@@ -557,6 +563,11 @@ interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOption
      * After the dotenv context is resolved, initialize any clients/secrets
      * or attach per-plugin state under ctx.plugins (by convention).
      * Runs parent → children (pre-order).
+     *
+     * **Scoping**: When the host provides an invoked subcommand filter,
+     * afterResolve only fires for plugins whose namespace matches the
+     * invoked command path. A plugin's afterResolve should never produce
+     * side effects for commands outside its subtree.
      */
     afterResolve?: (cli: GetDotenvCliPublic<TOptions, TArgs, TOpts, TGlobal>, ctx: GetDotenvCliCtx<TOptions>) => void | Promise<void>;
     /** Zod schema for this plugin's config slice (from config.plugins[…]). */
@@ -622,10 +633,14 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
      * Resolve options (strict) and compute dotenv context.
      * Stores the context on the instance under a symbol.
      *
-     * Options:
-     * - opts.runAfterResolve (default true): when false, skips running plugin
-     *   afterResolve hooks. Useful for top-level help rendering to avoid
-     *   long-running side-effects while still evaluating dynamic help text.
+     * @param customOptions - Partial options to overlay for this invocation.
+     * @param opts - Optional resolver behavior switches.
+     *   - `runAfterResolve` (default `true`): when false, skips running plugin
+     *     afterResolve hooks. Useful for top-level help rendering to avoid
+     *     long-running side-effects while still evaluating dynamic help text.
+     *   - `invokedSubcommand`: when provided, only the plugin subtree whose
+     *     namespace matches this name runs afterResolve hooks. When omitted,
+     *     all plugins run afterResolve (backward compatibility).
      */
     resolveAndLoad(customOptions?: Partial<TOptions>, opts?: ResolveAndLoadOptions): Promise<GetDotenvCliCtx<TOptions>>;
     /**
@@ -697,9 +712,15 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
      */
     install(): Promise<void>;
     /**
-     * Run afterResolve hooks for all plugins (parent → children).
+     * Run afterResolve hooks for registered plugins (parent → children).
+     * 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>;
 }
 
 /**