@karmaniverous/get-dotenv 5.2.5 → 6.0.0-0

package/dist/plugins-batch.d.mts

@@ -1,76 +1,6 @@
 import { Command } from 'commander';
 import { ZodType } from 'zod';
 
-/**
- * Minimal root options shape shared by CLI and generator layers.
- * Keep keys optional to respect exactOptionalPropertyTypes semantics.
- */
-type RootOptionsShape = {
-    env?: string;
-    vars?: string;
-    command?: string;
-    outputPath?: string;
-    shell?: string | boolean;
-    loadProcess?: boolean;
-    excludeAll?: boolean;
-    excludeDynamic?: boolean;
-    excludeEnv?: boolean;
-    excludeGlobal?: boolean;
-    excludePrivate?: boolean;
-    excludePublic?: boolean;
-    log?: boolean;
-    debug?: boolean;
-    capture?: boolean;
-    strict?: boolean;
-    redact?: boolean;
-    warnEntropy?: boolean;
-    entropyThreshold?: number;
-    entropyMinLength?: number;
-    entropyWhitelist?: string[];
-    redactPatterns?: string[];
-    defaultEnv?: string;
-    dotenvToken?: string;
-    dynamicPath?: string;
-    trace?: boolean | string[];
-    paths?: string;
-    pathsDelimiter?: string;
-    pathsDelimiterPattern?: string;
-    privateToken?: string;
-    varsDelimiter?: string;
-    varsDelimiterPattern?: string;
-    varsAssignor?: string;
-    varsAssignorPattern?: string;
-    scripts?: ScriptsTable;
-};
-/**
- * Scripts table shape (configurable shell type).
- */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
-    cmd: string;
-    shell?: TShell;
-}>;
-
-/**
- * Adapter-layer augmentation: add chainable helpers to GetDotenvCli without
- * coupling the core host to cliCore. Importing this module has side effects:
- * it extends the prototype and merges types for consumers.
- */
-declare module '../cliHost/GetDotenvCli' {
-    interface GetDotenvCli {
-        /**
-         * Attach legacy root flags to this CLI instance. Defaults come from
-         * baseRootOptionDefaults when none are provided.     */
-        attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
-            includeCommandOption?: boolean;
-        }): this;
-        /**
-         * Install a preSubcommand hook that merges CLI flags (including parent
-         * round-trip) and resolves the dotenv context before executing actions.
-         * Defaults come from baseRootOptionDefaults when none are provided.
-         */ passOptions(defaults?: Partial<RootOptionsShape>): this;
-    }
-}
-
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
@@ -165,14 +95,6 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
-/** * Per-invocation context shared with plugins and actions. */
-type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
-    optionsResolved: TOptions;
-    dotenv: ProcessEnv;
-    plugins?: Record<string, unknown>;
-    pluginConfigs?: Record<string, unknown>;
-};
-
 /** src/cliHost/definePlugin.ts
  * Plugin contracts for the GetDotenv CLI host.
  *
@@ -223,6 +145,14 @@ interface GetDotenvCliPlugin {
     use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
 }
 
+/** * Per-invocation context shared with plugins and actions. */
+type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
+    optionsResolved: TOptions;
+    dotenv: ProcessEnv;
+    plugins?: Record<string, unknown>;
+    pluginConfigs?: Record<string, unknown>;
+};
+
 /**
  * Batch services (neutral): resolve command and shell settings.
  * Shared by the generator path and the batch plugin to avoid circular deps.
@@ -241,7 +171,8 @@ type BatchPluginOptions = {
 /**
  * Batch plugin for the GetDotenv CLI host.
  *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI.
+ * Options:
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  * - logger: defaults to console.
  */

package/dist/plugins-batch.d.ts

@@ -1,76 +1,6 @@
 import { Command } from 'commander';
 import { ZodType } from 'zod';
 
-/**
- * Minimal root options shape shared by CLI and generator layers.
- * Keep keys optional to respect exactOptionalPropertyTypes semantics.
- */
-type RootOptionsShape = {
-    env?: string;
-    vars?: string;
-    command?: string;
-    outputPath?: string;
-    shell?: string | boolean;
-    loadProcess?: boolean;
-    excludeAll?: boolean;
-    excludeDynamic?: boolean;
-    excludeEnv?: boolean;
-    excludeGlobal?: boolean;
-    excludePrivate?: boolean;
-    excludePublic?: boolean;
-    log?: boolean;
-    debug?: boolean;
-    capture?: boolean;
-    strict?: boolean;
-    redact?: boolean;
-    warnEntropy?: boolean;
-    entropyThreshold?: number;
-    entropyMinLength?: number;
-    entropyWhitelist?: string[];
-    redactPatterns?: string[];
-    defaultEnv?: string;
-    dotenvToken?: string;
-    dynamicPath?: string;
-    trace?: boolean | string[];
-    paths?: string;
-    pathsDelimiter?: string;
-    pathsDelimiterPattern?: string;
-    privateToken?: string;
-    varsDelimiter?: string;
-    varsDelimiterPattern?: string;
-    varsAssignor?: string;
-    varsAssignorPattern?: string;
-    scripts?: ScriptsTable;
-};
-/**
- * Scripts table shape (configurable shell type).
- */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
-    cmd: string;
-    shell?: TShell;
-}>;
-
-/**
- * Adapter-layer augmentation: add chainable helpers to GetDotenvCli without
- * coupling the core host to cliCore. Importing this module has side effects:
- * it extends the prototype and merges types for consumers.
- */
-declare module '../cliHost/GetDotenvCli' {
-    interface GetDotenvCli {
-        /**
-         * Attach legacy root flags to this CLI instance. Defaults come from
-         * baseRootOptionDefaults when none are provided.     */
-        attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
-            includeCommandOption?: boolean;
-        }): this;
-        /**
-         * Install a preSubcommand hook that merges CLI flags (including parent
-         * round-trip) and resolves the dotenv context before executing actions.
-         * Defaults come from baseRootOptionDefaults when none are provided.
-         */ passOptions(defaults?: Partial<RootOptionsShape>): this;
-    }
-}
-
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
@@ -165,14 +95,6 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
-/** * Per-invocation context shared with plugins and actions. */
-type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
-    optionsResolved: TOptions;
-    dotenv: ProcessEnv;
-    plugins?: Record<string, unknown>;
-    pluginConfigs?: Record<string, unknown>;
-};
-
 /** src/cliHost/definePlugin.ts
  * Plugin contracts for the GetDotenv CLI host.
  *
@@ -223,6 +145,14 @@ interface GetDotenvCliPlugin {
     use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
 }
 
+/** * Per-invocation context shared with plugins and actions. */
+type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
+    optionsResolved: TOptions;
+    dotenv: ProcessEnv;
+    plugins?: Record<string, unknown>;
+    pluginConfigs?: Record<string, unknown>;
+};
+
 /**
  * Batch services (neutral): resolve command and shell settings.
  * Shared by the generator path and the batch plugin to avoid circular deps.
@@ -241,7 +171,8 @@ type BatchPluginOptions = {
 /**
  * Batch plugin for the GetDotenv CLI host.
  *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI.
+ * Options:
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  * - logger: defaults to console.
  */

package/dist/plugins-batch.mjs

@@ -235,9 +235,10 @@ const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     }
     return { absRootPath, paths };
 };
-const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
+const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv, globs, ignoreErrors, list, logger, 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.
+        Boolean(getDotenvCliOptions?.capture);
+    // Require a command only when not listing. In list mode, a command is optional.
     if (!command && !list) {
         logger.error(`No command provided. Use --command or --list.`);
         process.exit(0);
@@ -284,12 +285,25 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
             const hasCmd = (typeof command === 'string' && command.length > 0) ||
                 (Array.isArray(command) && command.length > 0);
             if (hasCmd) {
-                const envBag = getDotenvCliOptions !== undefined
-                    ? { getDotenvCliOptions: JSON.stringify(getDotenvCliOptions) }
-                    : undefined;
+                // Compose child env overlay from dotenv (drop undefined) and merged options
+                const overlay = {};
+                if (dotenvEnv) {
+                    for (const [k, v] of Object.entries(dotenvEnv)) {
+                        if (typeof v === 'string')
+                            overlay[k] = v;
+                    }
+                }
+                if (getDotenvCliOptions !== undefined) {
+                    try {
+                        overlay.getDotenvCliOptions = JSON.stringify(getDotenvCliOptions);
+                    }
+                    catch {
+                        // best-effort: omit if serialization fails
+                    }
+                }
                 await runCommand(command, shell, {
                     cwd: path,
-                    env: buildSpawnEnv(process.env, envBag),
+                    env: buildSpawnEnv(process.env, overlay),
                     stdio: capture ? 'pipe' : 'inherit',
                 });
             }
@@ -355,6 +369,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
     const ctx = cli.getCtx();
     const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
     const cfg = (cfgRaw || {});
+    const dotenvEnv = (ctx?.dotenv ?? {});
     // Resolve batch flags from the captured parent (batch) command.
     const raw = batchCmd.opts();
     const listFromParent = !!raw.list;
@@ -373,6 +388,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
         if (typeof commandOpt === 'string') {
             await execShellCommandBatch({
                 command: resolveCommand(scripts, commandOpt),
+                dotenvEnv,
                 globs,
                 ignoreErrors,
                 list: false,
@@ -384,6 +400,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
             return;
         }
         if (raw.list || localList) {
+            const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
             await execShellCommandBatch({
                 globs,
                 ignoreErrors,
@@ -391,7 +408,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
                 logger: loggerLocal,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
-                shell: (shell ?? false),
+                shell: (shell ?? shellBag.shell ?? false),
             });
             return;
         }
@@ -458,6 +475,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
     }
     await execShellCommandBatch({
         command: commandArg,
+        dotenvEnv,
         ...(envBag ? { getDotenvCliOptions: envBag } : {}),
         globs,
         ignoreErrors,
@@ -476,6 +494,7 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
     const logger = opts.logger ?? console;
     // Ensure context exists (host preSubcommand on root creates if missing).
     const ctx = cli.getCtx();
+    const dotenvEnv = (ctx?.dotenv ?? {});
     const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
     const cfg = (cfgRaw || {});
     const raw = thisCommand.opts();
@@ -498,6 +517,7 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const commandArg = resolved;
         await execShellCommandBatch({
             command: commandArg,
+            dotenvEnv,
             globs,
             ignoreErrors,
             list: false,
@@ -535,6 +555,7 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const shellOpt = opts.shell ?? cfg.shell ?? mergedBag.shell;
         await execShellCommandBatch({
             command: resolveCommand(scriptsOpt, commandOpt),
+            dotenvEnv,
             globs,
             ignoreErrors,
             list,
@@ -578,7 +599,8 @@ const BatchConfigSchema = z.object({
 /**
  * Batch plugin for the GetDotenv CLI host.
  *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI.
+ * Options:
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  * - logger: defaults to console.
  */
@@ -590,12 +612,32 @@ const batchPlugin = (opts = {}) => definePlugin({
     setup(cli) {
         const ns = cli.ns('batch');
         const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
+        const host = cli;
+        const pluginId = 'batch';
+        const GROUP = `plugin:${pluginId}`;
         ns.description('Batch command execution across multiple working directories.')
             .enablePositionalOptions()
             .passThroughOptions()
-            .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
-            .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
-            .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
+            // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
+            .addOption((() => {
+            const opt = host.createDynamicOption('-p, --pkg-cwd', (cfg) => {
+                const slice = cfg.plugins.batch ?? {};
+                const on = !!slice.pkgCwd;
+                return `use nearest package directory as current working directory${on ? ' (default)' : ''}`;
+            });
+            opt.__group = GROUP;
+            return opt;
+        })())
+            .addOption((() => {
+            const opt = host.createDynamicOption('-r, --root-path <string>', (cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.plugins.batch?.rootPath || './')})`);
+            opt.__group = GROUP;
+            return opt;
+        })())
+            .addOption((() => {
+            const opt = host.createDynamicOption('-g, --globs <string>', (cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.plugins.batch?.globs || '*')})`);
+            opt.__group = GROUP;
+            return opt;
+        })())
             .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')