@karmaniverous/get-dotenv 7.0.6 → 7.0.8

package/dist/plugins-batch.d.ts

@@ -272,7 +272,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.
@@ -358,6 +358,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.
@@ -451,6 +457,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[…]). */
@@ -550,6 +561,11 @@ interface ExecShellCommandBatchOptions {
      * an array is treated as argv for shell‑off execution.
      */
     command?: string | string[];
+    /**
+     * Maximum number of concurrent executions when {@link ExecShellCommandBatchOptions.parallel} is true.
+     * Defaults to {@link defaultConcurrency}.
+     */
+    concurrency?: number;
     /**
      * Merged root CLI options bag (JSON‑serializable) forwarded for nested composition
      * by downstream executors. Used to compute child overlays deterministically.
@@ -575,6 +591,11 @@ interface ExecShellCommandBatchOptions {
      * Logger used for headings, listings, and diagnostics.
      */
     logger: Logger;
+    /**
+     * When true, execute commands across discovered directories in parallel.
+     * Output is buffered per-directory and printed in discovery order.
+     */
+    parallel?: boolean;
     /**
      * Resolve the batch root from the nearest package directory instead of CWD.
      */
@@ -597,12 +618,16 @@ interface ExecShellCommandBatchOptions {
 interface BatchParentInvokerFlags {
     /** Command to execute. */
     command?: string;
+    /** Maximum concurrent executions in parallel mode. */
+    concurrency?: number;
     /** Space-delimited glob patterns. */
     globs?: string;
     /** List directories without executing. */
     list?: boolean;
     /** Ignore errors and continue. */
     ignoreErrors?: boolean;
+    /** Execute commands in parallel across directories. */
+    parallel?: boolean;
     /** Use package directory as root. */
     pkgCwd?: boolean;
     /** Root path for discovery. */
@@ -625,6 +650,7 @@ interface BatchCmdSubcommandOptions {
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  */
 declare const batchPlugin: (opts?: BatchPluginOptions) => PluginWithInstanceHelpers<GetDotenvOptions, {
+    concurrency?: number | undefined;
     scripts?: Record<string, string | {
         cmd: string;
         shell?: string | boolean | undefined;
@@ -632,6 +658,7 @@ declare const batchPlugin: (opts?: BatchPluginOptions) => PluginWithInstanceHelp
     shell?: string | boolean | undefined;
     rootPath?: string | undefined;
     globs?: string | undefined;
+    parallel?: boolean | undefined;
     pkgCwd?: boolean | undefined;
 }, [], {}, {}>;
 /**

package/dist/plugins-batch.mjs

@@ -1,4 +1,4 @@
-import { r as readMergedOptions, g as definePlugin } from './chunks/readMergedOptions-CraAnYdB.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-BT1C87_u.mjs';
 import 'execa';
 import 'radash';
 import 'node:buffer';
@@ -10,16 +10,56 @@ import 'url';
 import { Command } from '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import { packageDirectory } from 'package-directory';
 import 'yaml';
 import { z } from 'zod';
 import { c as composeNestedEnv, m as maybePreserveNodeEvalArgv } from './chunks/invoke-DuRPU1oC.mjs';
-import { c as runCommand, b as buildSpawnEnv, a as resolveShell, r as resolveCommand } from './chunks/spawnEnv-CKgnHGpr.mjs';
+import { b as buildSpawnEnv, c as runCommand, d as runCommandResult, a as resolveShell, r as resolveCommand } from './chunks/spawnEnv-DvisqPiU.mjs';
 import { globby } from 'globby';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import os from 'os';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 
+/**
+ * Default concurrency limit for parallel batch execution.
+ * Uses `os.availableParallelism()` when available, otherwise falls back to CPU count.
+ */
+const defaultConcurrency = typeof os.availableParallelism === 'function'
+    ? os.availableParallelism()
+    : os.cpus().length;
+/**
+ * Zod schema for a single script entry (string or object).
+ */
+const ScriptSchema = z.union([
+    z.string(),
+    z.object({
+        /** Command string to execute. */
+        cmd: z.string(),
+        /** Optional shell override for this script entry. */
+        shell: z.union([z.string(), z.boolean()]).optional(),
+    }),
+]);
+/**
+ * Zod schema for batch plugin configuration.
+ */
+const batchPluginConfigSchema = z.object({
+    /** Maximum concurrent executions in parallel mode. */
+    concurrency: z.number().int().positive().optional(),
+    /** Optional scripts table scoped to the batch plugin. */
+    scripts: z.record(z.string(), ScriptSchema).optional(),
+    /** Optional default shell for batch execution (overridden by per-script shell when present). */
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    /** Root path for discovery, relative to CWD (or package root when pkgCwd is true). */
+    rootPath: z.string().optional(),
+    /** Space-delimited glob patterns used to discover directories. */
+    globs: z.string().optional(),
+    /** Execute commands in parallel across discovered directories. */
+    parallel: z.boolean().optional(),
+    /** When true, resolve the batch root from the nearest package directory. */
+    pkgCwd: z.boolean().optional(),
+});
+
 const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     let cwd = process.cwd();
     if (pkgCwd) {
@@ -47,7 +87,7 @@ const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
  * Execute a batch of commands across multiple directories.
  * Discovers targets via globs/rootPath and runs the command in each.
  */
-const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
+const execShellCommandBatch = async ({ command, concurrency, getDotenvCliOptions, dotenvEnv, globs, ignoreErrors, list, logger, parallel, pkgCwd, rootPath, shell, }) => {
     const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
         Boolean(getDotenvCliOptions?.capture);
     // Require a command only when not listing. In list mode, a command is optional.
@@ -64,7 +104,9 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv,
     });
     const headerTitle = list
         ? 'Listing working directories...'
-        : 'Executing command batch...';
+        : parallel
+            ? 'Executing command batch (parallel)...'
+            : 'Executing command batch...';
     logger.info('');
     const headerRootPath = `ROOT:  ${absRootPath}`;
     const headerGlobs = `GLOBS: ${globs}`;
@@ -81,39 +123,130 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv,
     logger.info(headerRootPath);
     logger.info(headerGlobs);
     logger.info(headerCommand);
-    for (const path of paths) {
-        // Write path and command to console.
-        const pathLabel = `CWD:   ${path}`;
-        if (list) {
-            logger.info(pathLabel);
-            continue;
+    // List mode: no parallelism needed.
+    if (list) {
+        for (const p of paths) {
+            logger.info(`CWD:   ${p}`);
         }
         logger.info('');
-        logger.info('*'.repeat(pathLabel.length));
-        logger.info(pathLabel);
-        logger.info(headerCommand);
-        // Execute command.
-        try {
-            const hasCmd = (typeof command === 'string' && command.length > 0) ||
-                (Array.isArray(command) && command.length > 0);
-            if (hasCmd) {
-                // Compose child env overlay (dotenv + nested bag)
-                const overlay = composeNestedEnv(getDotenvCliOptions ?? {}, dotenvEnv ?? {});
-                await runCommand(command, shell, {
-                    cwd: path,
-                    env: buildSpawnEnv(process.env, overlay),
-                    stdio: capture ? 'pipe' : 'inherit',
-                });
+        return;
+    }
+    // Narrow command to a non-empty string or array after validation.
+    const validCommand = typeof command === 'string' && command.length > 0
+        ? command
+        : Array.isArray(command) && command.length > 0
+            ? command
+            : undefined;
+    if (!validCommand) {
+        logger.error(`No command provided. Use --command or --list.`);
+        process.exit(0);
+    }
+    // Compose child env overlay once (shared across all paths).
+    const overlay = composeNestedEnv(getDotenvCliOptions ?? {}, dotenvEnv ?? {});
+    const spawnEnv = buildSpawnEnv(process.env, overlay);
+    if (parallel) {
+        // Parallel execution with concurrency-limited pool.
+        const limit = concurrency ?? defaultConcurrency;
+        const results = [];
+        // Simple semaphore-based concurrency pool.
+        let active = 0;
+        let nextIdx = 0;
+        const total = paths.length;
+        results.length = total;
+        await new Promise((resolveAll, rejectAll) => {
+            let settled = false;
+            let completedCount = 0;
+            const tryLaunch = () => {
+                while (active < limit && nextIdx < total) {
+                    const idx = nextIdx++;
+                    const dirPath = paths[idx];
+                    active++;
+                    runCommandResult(validCommand, shell, {
+                        cwd: dirPath,
+                        env: spawnEnv,
+                    })
+                        .then((res) => {
+                        results[idx] = {
+                            dirPath,
+                            exitCode: res.exitCode,
+                            stdout: res.stdout,
+                            stderr: res.stderr,
+                        };
+                    })
+                        .catch((err) => {
+                        results[idx] = {
+                            dirPath,
+                            exitCode: 1,
+                            stdout: '',
+                            stderr: String(err),
+                            error: err,
+                        };
+                    })
+                        .finally(() => {
+                        active--;
+                        completedCount++;
+                        if (completedCount === total && !settled) {
+                            settled = true;
+                            resolveAll();
+                        }
+                        else {
+                            tryLaunch();
+                        }
+                    });
+                }
+            };
+            if (total === 0) {
+                resolveAll();
             }
             else {
-                // Should not occur due to the early guard; retain for type safety.
-                logger.error(`No command provided. Use --command or --list.`);
-                process.exit(0);
+                tryLaunch();
+            }
+        });
+        // Print results in discovery order.
+        const failures = [];
+        for (const result of results) {
+            const pathLabel = `CWD:   ${result.dirPath}`;
+            logger.info('');
+            logger.info('*'.repeat(pathLabel.length));
+            logger.info(pathLabel);
+            logger.info(headerCommand);
+            if (result.stdout) {
+                process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+            }
+            if (result.stderr) {
+                process.stderr.write(result.stderr + (result.stderr.endsWith('\n') ? '' : '\n'));
+            }
+            if (result.exitCode !== 0) {
+                failures.push(result);
+            }
+        }
+        if (failures.length > 0 && !ignoreErrors) {
+            logger.error('');
+            logger.error(`${String(failures.length)} of ${String(total)} directories failed:`);
+            for (const f of failures) {
+                logger.error(`  ${f.dirPath} (exit code ${String(f.exitCode)})`);
             }
         }
-        catch (error) {
-            if (!ignoreErrors) {
-                throw error;
+    }
+    else {
+        // Sequential execution (original behavior).
+        for (const p of paths) {
+            const pathLabel = `CWD:   ${p}`;
+            logger.info('');
+            logger.info('*'.repeat(pathLabel.length));
+            logger.info(pathLabel);
+            logger.info(headerCommand);
+            try {
+                await runCommand(validCommand, shell, {
+                    cwd: p,
+                    env: spawnEnv,
+                    stdio: capture ? 'pipe' : 'inherit',
+                });
+            }
+            catch (error) {
+                if (!ignoreErrors) {
+                    throw error;
+                }
             }
         }
     }
@@ -153,6 +286,8 @@ const attachBatchCmdAction = (plugin, cli, batchCmd, pluginOpts, cmd) => {
             : typeof cfg.rootPath === 'string'
                 ? cfg.rootPath
                 : './';
+        const parallel = g.parallel !== undefined ? g.parallel : Boolean(cfg.parallel);
+        const concurrency = typeof g.concurrency === 'number' ? g.concurrency : cfg.concurrency;
         // Resolve scripts/shell with precedence:
         // plugin opts → plugin config → merged root CLI options
         const scripts = pluginOpts.scripts ?? cfg.scripts ?? mergedBag.scripts ?? undefined;
@@ -163,11 +298,13 @@ const attachBatchCmdAction = (plugin, cli, batchCmd, pluginOpts, cmd) => {
             if (typeof commandOpt === 'string') {
                 await execShellCommandBatch({
                     command: resolveCommand(scripts, commandOpt),
+                    ...(concurrency !== undefined ? { concurrency } : {}),
                     dotenvEnv,
                     globs,
                     ignoreErrors,
                     list: false,
                     logger,
+                    parallel,
                     ...(pkgCwd ? { pkgCwd } : {}),
                     rootPath,
                     shell: resolveShell(scripts, commandOpt, shell),
@@ -183,10 +320,12 @@ const attachBatchCmdAction = (plugin, cli, batchCmd, pluginOpts, cmd) => {
                         ? rootShell
                         : false;
                 await execShellCommandBatch({
+                    ...(concurrency !== undefined ? { concurrency } : {}),
                     globs,
                     ignoreErrors,
                     list: true,
                     logger,
+                    parallel,
                     ...(pkgCwd ? { pkgCwd } : {}),
                     rootPath,
                     shell: listShell,
@@ -208,23 +347,29 @@ const attachBatchCmdAction = (plugin, cli, batchCmd, pluginOpts, cmd) => {
         const shellExec = shell ?? mergedBag.shell;
         const resolved = resolveCommand(scriptsExec, input);
         const shellSetting = resolveShell(scriptsExec, input, shellExec);
-        // Preserve argv array only for shell-off Node -e snippets to avoid
-        // lossy re-tokenization (Windows/PowerShell quoting). For simple
-        // commands (e.g., "echo OK") keep string form to satisfy unit tests.
+        // Preserve argv array to avoid lossy re-tokenization (Windows/
+        // PowerShell quoting). When the command was not resolved to a script
+        // (i.e. resolved === input), keep the original argv tokens so that
+        // _execNormalized can pass them individually to execa — both in
+        // shell-off mode (where stripOuterQuotes handles argv) and in shell
+        // mode (where execa applies per-platform shell escaping per arg).
         let commandArg = resolved;
-        if (shellSetting === false && resolved === input) {
-            const preserved = maybePreserveNodeEvalArgv(args);
-            if (preserved !== args)
-                commandArg = preserved;
+        if (resolved === input) {
+            // Always pass the argv array to avoid lossy re-tokenization.
+            // For shell-off + node -e, apply outer-quote stripping first.
+            commandArg =
+                shellSetting === false ? maybePreserveNodeEvalArgv(args) : args;
         }
         await execShellCommandBatch({
             command: commandArg,
+            ...(concurrency !== undefined ? { concurrency } : {}),
             dotenvEnv,
             ...(envBag ? { getDotenvCliOptions: envBag } : {}),
             globs,
             ignoreErrors,
             list: false,
             logger,
+            parallel,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
             shell: shellSetting,
@@ -279,6 +424,8 @@ const attachBatchDefaultAction = (plugin, cli, pluginOpts, parent) => {
         const ignoreErrors = Boolean(opts.ignoreErrors);
         let globs = typeof opts.globs === 'string' ? opts.globs : (cfg.globs ?? '*');
         const list = Boolean(opts.list);
+        const parallel = opts.parallel !== undefined ? opts.parallel : Boolean(cfg.parallel);
+        const concurrency = typeof opts.concurrency === 'number' ? opts.concurrency : cfg.concurrency;
         const pkgCwd = opts.pkgCwd !== undefined ? opts.pkgCwd : Boolean(cfg.pkgCwd);
         const rootPath = typeof opts.rootPath === 'string'
             ? opts.rootPath
@@ -297,11 +444,13 @@ const attachBatchDefaultAction = (plugin, cli, pluginOpts, parent) => {
             const commandArg = resolved;
             await execShellCommandBatch({
                 command: commandArg,
+                ...(concurrency !== undefined ? { concurrency } : {}),
                 dotenvEnv,
                 globs,
                 ignoreErrors,
                 list: false,
                 logger,
+                parallel,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
                 shell: shellSetting,
@@ -316,10 +465,12 @@ const attachBatchDefaultAction = (plugin, cli, pluginOpts, parent) => {
                 globs = [globs, extra].filter(Boolean).join(' ');
             const shellMerged = pluginOpts.shell ?? cfg.shell ?? merged.shell ?? false;
             await execShellCommandBatch({
+                ...(concurrency !== undefined ? { concurrency } : {}),
                 globs,
                 ignoreErrors,
                 list: true,
                 logger,
+                parallel,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
                 shell: shellMerged,
@@ -336,11 +487,13 @@ const attachBatchDefaultAction = (plugin, cli, pluginOpts, parent) => {
             const shellOpt = pluginOpts.shell ?? cfg.shell ?? merged.shell;
             await execShellCommandBatch({
                 command: resolveCommand(scriptsOpt, commandOpt),
+                ...(concurrency !== undefined ? { concurrency } : {}),
                 dotenvEnv,
                 globs,
                 ignoreErrors,
                 list,
                 logger,
+                parallel,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
                 shell: resolveShell(scriptsOpt, commandOpt, shellOpt),
@@ -351,10 +504,12 @@ const attachBatchDefaultAction = (plugin, cli, pluginOpts, parent) => {
         // list only (explicit --list without --command)
         const shellOnly = pluginOpts.shell ?? cfg.shell ?? merged.shell ?? false;
         await execShellCommandBatch({
+            ...(concurrency !== undefined ? { concurrency } : {}),
             globs,
             ignoreErrors,
             list: true,
             logger,
+            parallel,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
             shell: shellOnly,
@@ -399,37 +554,16 @@ function attachBatchOptions(plugin, cli) {
         .option('-c, --command <string>', 'command executed according to the base shell resolution')
         .option('-l, --list', 'list working directories without executing command')
         .option('-e, --ignore-errors', 'ignore errors and continue with next path')
+        .option('-P, --parallel', 'execute commands in parallel across directories')
+        .option('-C, --concurrency <n>', `max concurrent executions in parallel mode (default: ${String(defaultConcurrency)})`, (v) => {
+        const n = Number.parseInt(v, 10);
+        if (Number.isNaN(n) || n < 1)
+            throw new Error(`invalid concurrency: ${v}`);
+        return n;
+    })
         .argument('[command...]'));
 }
 
-/**
- * Zod schema for a single script entry (string or object).
- */
-const ScriptSchema = z.union([
-    z.string(),
-    z.object({
-        /** Command string to execute. */
-        cmd: z.string(),
-        /** Optional shell override for this script entry. */
-        shell: z.union([z.string(), z.boolean()]).optional(),
-    }),
-]);
-/**
- * Zod schema for batch plugin configuration.
- */
-const batchPluginConfigSchema = z.object({
-    /** Optional scripts table scoped to the batch plugin. */
-    scripts: z.record(z.string(), ScriptSchema).optional(),
-    /** Optional default shell for batch execution (overridden by per-script shell when present). */
-    shell: z.union([z.string(), z.boolean()]).optional(),
-    /** Root path for discovery, relative to CWD (or package root when pkgCwd is true). */
-    rootPath: z.string().optional(),
-    /** Space-delimited glob patterns used to discover directories. */
-    globs: z.string().optional(),
-    /** When true, resolve the batch root from the nearest package directory. */
-    pkgCwd: z.boolean().optional(),
-});
-
 /**
  * @packageDocumentation
  * Batch plugin subpath. Provides the `batch` command for executing a command

package/dist/plugins-cmd.d.ts

@@ -272,7 +272,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.
@@ -358,6 +358,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.
@@ -451,6 +457,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[…]). */

package/dist/plugins-cmd.mjs

@@ -1,5 +1,5 @@
 import 'radash';
-import './chunks/readMergedOptions-CraAnYdB.mjs';
+import './chunks/readMergedOptions-BT1C87_u.mjs';
 import 'execa';
 import 'node:buffer';
 import 'fs-extra';
@@ -10,13 +10,13 @@ import 'url';
 import '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import 'package-directory';
 import 'yaml';
 import 'zod';
-export { c as cmdPlugin } from './chunks/index-Dd6S1nZ-.mjs';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+export { c as cmdPlugin } from './chunks/index-DnG3N6yj.mjs';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
-import './chunks/spawnEnv-CKgnHGpr.mjs';
+import './chunks/spawnEnv-DvisqPiU.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
-import './chunks/resolveCliOptions-BMBkWDYJ.mjs';
+import './chunks/resolveCliOptions-BbfouWSK.mjs';

package/dist/plugins-init.d.ts

@@ -272,7 +272,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.
@@ -358,6 +358,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.
@@ -451,6 +457,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[…]). */

package/dist/plugins-init.mjs

@@ -1,4 +1,4 @@
-import { r as readMergedOptions, g as definePlugin } from './chunks/readMergedOptions-CraAnYdB.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-BT1C87_u.mjs';
 import 'execa';
 import 'radash';
 import 'node:buffer';
@@ -10,14 +10,14 @@ import 'url';
 import '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import './chunks/loader-V1vbmtyw.mjs';
+import './chunks/loader-C3DtD6HB.mjs';
 import { packageDirectory } from 'package-directory';
 import 'yaml';
 import 'zod';
 import { stdin, stdout } from 'node:process';
 import { createInterface } from 'readline/promises';
 import { fileURLToPath } from 'node:url';
-import './chunks/readDotenvCascade-Dgx4SC1p.mjs';
+import './chunks/readDotenvCascade-CfFPgLCp.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 
 /**