@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/plugins-batch.mjs

@@ -1,9 +1,92 @@
 import { Command } from 'commander';
-import { globby } from 'globby';
-import { packageDirectory } from 'package-directory';
+import { z } from 'zod';
+import 'fs-extra';
 import path from 'path';
+import { packageDirectory } from 'package-directory';
+import 'url';
+import 'yaml';
+import 'nanoid';
+import 'dotenv';
+import 'crypto';
+import { globby } from 'globby';
 import { execa, execaCommand } from 'execa';
-import { z } from 'zod';
+
+/**
+ * Zod schemas for configuration files discovered by the new loader.
+ *
+ * Notes:
+ * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
+ * - RESOLVED: normalized shapes (paths always string[]).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
+ */
+// String-only env value map
+const stringMap = z.record(z.string(), z.string());
+const envStringMap = z.record(z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+const getDotenvConfigSchemaRaw = z.object({
+    dotenvToken: z.string().optional(),
+    privateToken: z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: z.array(z.string()).optional(),
+    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * Canonical source of truth for options shape. Public types are derived
+ * from these schemas (see consumers via z.output\<\>).
+ */
+// Minimal process env representation: string values or undefined to indicate "unset".
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    logger: z.unknown().optional(),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+});
+
+/**
+ * Instance-bound plugin config store.
+ * Host stores the validated/interpolated slice per plugin instance.
+ * The store is intentionally private to this module; definePlugin()
+ * provides a typed accessor that reads from this store for the calling
+ * plugin instance.
+ */
+const PLUGIN_CONFIG_STORE = new WeakMap();
+const _getPluginConfigForInstance = (plugin) => PLUGIN_CONFIG_STORE.get(plugin);
 
 /** src/cliHost/definePlugin.ts
  * Plugin contracts for the GetDotenv CLI host.
@@ -12,30 +95,66 @@ import { z } from 'zod';
  * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
  * nominal class identity issues (private fields) in downstream consumers.
  */
-/**
- * Define a GetDotenv CLI plugin with compositional helpers.
- *
- * @example
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
- */
-const definePlugin = (spec) => {
+/* eslint-disable tsdoc/syntax */
+function definePlugin(spec) {
     const { children = [], ...rest } = spec;
-    const plugin = {
+    // Default to a strict empty-object schema so “no-config” plugins fail fast
+    // on unknown keys and provide a concrete {} at runtime.
+    const effectiveSchema = spec.configSchema ?? z.object({}).strict();
+    // Build base plugin first, then extend with instance-bound helpers.
+    const base = {
         ...rest,
+        // Always carry a schema (strict empty by default) to simplify host logic
+        // and improve inference/ergonomics for plugin authors.
+        configSchema: effectiveSchema,
         children: [...children],
         use(child) {
             this.children.push(child);
             return this;
         },
     };
-    return plugin;
-};
+    // Attach instance-bound helpers on the returned plugin object.
+    const extended = base;
+    extended.readConfig = function (_cli) {
+        // Config is stored per-plugin-instance by the host (WeakMap in computeContext).
+        const value = _getPluginConfigForInstance(extended);
+        if (value === undefined) {
+            // Guard: host has not resolved config yet (incorrect lifecycle usage).
+            throw new Error('Plugin config not available. Ensure resolveAndLoad() has been called before readConfig().');
+        }
+        return value;
+    };
+    // Plugin-bound dynamic option factory
+    extended.createPluginDynamicOption = function (cli, flags, desc, parser, defaultValue) {
+        return cli.createDynamicOption(flags, (cfg) => {
+            // Prefer the validated slice stored per instance; fallback to help-bag
+            // (by-id) so top-level `-h` can render effective defaults before resolve.
+            const fromStore = _getPluginConfigForInstance(extended);
+            const id = extended.id;
+            let fromBag;
+            if (!fromStore && id) {
+                const maybe = cfg.plugins[id];
+                if (maybe && typeof maybe === 'object') {
+                    fromBag = maybe;
+                }
+            }
+            // Always provide a concrete object to dynamic callbacks:
+            // - With a schema: computeContext stores the parsed object.
+            // - Without a schema: computeContext stores {}.
+            // - Help-time fallback: coalesce to {} when only a by-id bag exists.
+            const cfgVal = (fromStore ?? fromBag ?? {});
+            return desc(cfg, cfgVal);
+        }, parser, defaultValue);
+    };
+    return extended;
+}
 
 // Minimal tokenizer for shell-off execution:
 // Splits by whitespace while preserving quoted segments (single or double quotes).
-const tokenize = (command) => {
+// Optionally preserve doubled quotes inside quoted segments:
+// - default: "" => " (Windows/PowerShell style literal-quote escape)
+// - preserveDoubledQuotes: true => "" stays "" (needed for Node -e payloads)
+const tokenize = (command, opts) => {
     const out = [];
     let cur = '';
     let quote = null;
@@ -43,12 +162,16 @@ const tokenize = (command) => {
         const c = command.charAt(i);
         if (quote) {
             if (c === quote) {
-                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
-                // "" -> " and '' -> '
+                // Support doubled quotes inside a quoted segment:
+                // default: "" -> " and '' -> ' (Windows/PowerShell style)
+                // preserve: keep as "" to allow empty string literals in Node -e payloads
                 const next = command.charAt(i + 1);
                 if (next === quote) {
-                    cur += quote;
-                    i += 1; // skip the second quote
+                    {
+                        // Collapse to a single literal quote
+                        cur += quote;
+                        i += 1; // skip the second quote
+                    }
                 }
                 else {
                     // end of quoted segment
@@ -103,6 +226,17 @@ const stripOuterQuotes = (s) => {
     }
     return out;
 };
+// Extract exitCode/stdout/stderr from execa result or error in a tolerant way.
+const pickResult = (r) => {
+    const exit = r.exitCode;
+    const stdoutVal = r.stdout;
+    const stderrVal = r.stderr;
+    return {
+        exitCode: typeof exit === 'number' ? exit : Number.NaN,
+        stdout: typeof stdoutVal === 'string' ? stdoutVal : '',
+        stderr: typeof stderrVal === 'string' ? stderrVal : '',
+    };
+};
 // Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
 // expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
 const sanitizeEnv = (env) => {
@@ -111,19 +245,19 @@ const sanitizeEnv = (env) => {
     const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
     return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 };
-const runCommand = async (command, shell, opts) => {
+async function runCommand(command, shell, opts) {
     if (shell === false) {
         let file;
         let args = [];
-        if (Array.isArray(command)) {
-            file = command[0];
-            args = command.slice(1).map(stripOuterQuotes);
-        }
-        else {
+        if (typeof command === 'string') {
             const tokens = tokenize(command);
             file = tokens[0];
             args = tokens.slice(1);
         }
+        else {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
         if (!file)
             return 0;
         dbg('exec (plain)', { file, args, stdio: opts.stdio });
@@ -136,16 +270,15 @@ const runCommand = async (command, shell, opts) => {
             plainOpts.env = envSan;
         if (opts.stdio !== undefined)
             plainOpts.stdio = opts.stdio;
-        const result = await execa(file, args, plainOpts);
-        if (opts.stdio === 'pipe' && result.stdout) {
-            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+        const ok = pickResult((await execa(file, args, plainOpts)));
+        if (opts.stdio === 'pipe' && ok.stdout) {
+            process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
         }
-        const exit = result?.exitCode;
-        dbg('exit (plain)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
+        dbg('exit (plain)', { exitCode: ok.exitCode });
+        return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
     }
     else {
-        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        const commandStr = typeof command === 'string' ? command : command.join(' ');
         dbg('exec (shell)', {
             shell: typeof shell === 'string' ? shell : 'custom',
             stdio: opts.stdio,
@@ -159,17 +292,29 @@ const runCommand = async (command, shell, opts) => {
             shellOpts.env = envSan;
         if (opts.stdio !== undefined)
             shellOpts.stdio = opts.stdio;
-        const result = await execaCommand(commandStr, shellOpts);
-        const out = result?.stdout;
-        if (opts.stdio === 'pipe' && out) {
-            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+        const ok = pickResult((await execaCommand(commandStr, shellOpts)));
+        if (opts.stdio === 'pipe' && ok.stdout) {
+            process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
         }
-        const exit = result?.exitCode;
-        dbg('exit (shell)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
+        dbg('exit (shell)', { exitCode: ok.exitCode });
+        return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
     }
-};
+}
 
+/** src/cliCore/spawnEnv.ts
+ * Build a sanitized environment bag for child processes.
+ *
+ * Requirements addressed:
+ * - Provide a single helper (buildSpawnEnv) to normalize/dedupe child env.
+ * - Drop undefined values (exactOptional semantics).
+ * - On Windows, dedupe keys case-insensitively and prefer the last value,
+ *   preserving the latest key's casing. Ensure HOME fallback from USERPROFILE.
+ *   Normalize TMP/TEMP consistency when either is present.
+ * - On POSIX, keep keys as-is; when a temp dir key is present (TMPDIR/TMP/TEMP),
+ *   ensure TMPDIR exists for downstream consumers that expect it.
+ *
+ * Adapter responsibility: pure mapping; no business logic.
+ */
 const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
 /** Build a sanitized env for child processes from base + overlay. */
 const buildSpawnEnv = (base, overlay) => {
@@ -235,9 +380,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 +430,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',
                 });
             }
@@ -340,7 +499,7 @@ const resolveShell = (scripts, command, shell) => scripts && typeof scripts[comm
  * Build the default "cmd" subcommand action for the batch plugin.
  * Mirrors the original inline implementation with identical behavior.
  */
-const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _subOpts, _thisCommand) => {
+const buildDefaultCmdAction = (plugin, cli, batchCmd, opts) => async (commandParts, _subOpts, _thisCommand) => {
     const loggerLocal = opts.logger ?? console;
     // Guard: when invoked without positional args (e.g., `batch --list`),
     // defer entirely to the parent action handler.
@@ -352,9 +511,8 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
         ? argsRaw.filter((t) => t !== '-l' && t !== '--list')
         : argsRaw;
     // Access merged per-plugin config from host context (if any).
-    const ctx = cli.getCtx();
-    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
-    const cfg = (cfgRaw || {});
+    const cfg = plugin.readConfig(cli);
+    const dotenvEnv = (cli.getCtx()?.dotenv ?? {});
     // Resolve batch flags from the captured parent (batch) command.
     const raw = batchCmd.opts();
     const listFromParent = !!raw.list;
@@ -373,6 +531,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 +543,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 +551,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
                 logger: loggerLocal,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
-                shell: (shell ?? false),
+                shell: shell ?? shellBag.shell ?? false,
             });
             return;
         }
@@ -415,7 +575,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
             logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
-            shell: (shell ?? shellBag.shell ?? false),
+            shell: shell ?? shellBag.shell ?? false,
         });
         return;
     }
@@ -458,6 +618,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
     }
     await execShellCommandBatch({
         command: commandArg,
+        dotenvEnv,
         ...(envBag ? { getDotenvCliOptions: envBag } : {}),
         globs,
         ignoreErrors,
@@ -472,12 +633,11 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
 /**
  * Build the parent "batch" action handler (no explicit subcommand).
  */
-const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
-    const logger = opts.logger ?? console;
+const buildParentAction = (plugin, cli, opts) => async (commandParts, thisCommand) => {
+    const loggerLocal = opts.logger ?? console;
     // Ensure context exists (host preSubcommand on root creates if missing).
-    const ctx = cli.getCtx();
-    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
-    const cfg = (cfgRaw || {});
+    const dotenvEnv = (cli.getCtx()?.dotenv ?? {});
+    const cfg = plugin.readConfig(cli);
     const raw = thisCommand.opts();
     const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
     const ignoreErrors = !!raw.ignoreErrors;
@@ -498,10 +658,11 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const commandArg = resolved;
         await execShellCommandBatch({
             command: commandArg,
+            dotenvEnv,
             globs,
             ignoreErrors,
             list: false,
-            logger,
+            logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
             shell: shellSetting,
@@ -514,19 +675,20 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         if (extra.length > 0)
             globs = [globs, extra].filter(Boolean).join(' ');
         const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        const shellMerged = opts.shell ?? cfg.shell ?? mergedBag.shell ?? false;
         await execShellCommandBatch({
             globs,
             ignoreErrors,
             list: true,
-            logger,
+            logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
-            shell: (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false),
+            shell: shellMerged,
         });
         return;
     }
     if (!commandOpt && !list) {
-        logger.error(`No command provided. Use --command or --list.`);
+        loggerLocal.error(`No command provided. Use --command or --list.`);
         process.exit(0);
     }
     if (typeof commandOpt === 'string') {
@@ -535,10 +697,11 @@ 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,
-            logger,
+            logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
             shell: resolveShell(scriptsOpt, commandOpt, shellOpt),
@@ -547,15 +710,15 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
     }
     // list only (explicit --list without --command)
     const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
-    const shellOnly = (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false);
+    const shellOnly = opts.shell ?? cfg.shell ?? mergedBag.shell ?? false;
     await execShellCommandBatch({
         globs,
         ignoreErrors,
         list: true,
-        logger,
+        logger: loggerLocal,
         ...(pkgCwd ? { pkgCwd } : {}),
         rootPath,
-        shell: (shellOnly ?? false),
+        shell: shellOnly,
     });
 };
 
@@ -578,37 +741,56 @@ 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.
  */
-const batchPlugin = (opts = {}) => definePlugin({
-    id: 'batch',
-    // Host validates this when config-loader is enabled; plugins may also
-    // re-validate at action time as a safety belt.
-    configSchema: BatchConfigSchema,
-    setup(cli) {
-        const ns = cli.ns('batch');
-        const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
-        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', '*')
-            .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')
-            .argument('[command...]')
-            .addCommand(new Command()
-            .name('cmd')
-            .description('execute command, conflicts with --command option (default subcommand)')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .argument('[command...]')
-            .action(buildDefaultCmdAction(cli, batchCmd, opts)), { isDefault: true })
-            .action(buildParentAction(cli, opts));
-    },
-});
+const batchPlugin = (opts = {}) => {
+    const plugin = definePlugin({
+        id: 'batch',
+        // Host validates this when config-loader is enabled; plugins may also
+        // re-validate at action time as a safety belt.
+        configSchema: BatchConfigSchema,
+        setup(cli) {
+            const ns = cli.ns('batch');
+            const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
+            const pluginId = 'batch';
+            const GROUP = `plugin:${pluginId}`;
+            ns.description('Batch command execution across multiple working directories.')
+                .enablePositionalOptions()
+                .passThroughOptions()
+                // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
+                .addOption((() => {
+                const opt = plugin.createPluginDynamicOption(cli, '-p, --pkg-cwd', (_bag, cfg) => `use nearest package directory as current working directory${cfg.pkgCwd ? ' (default)' : ''}`);
+                cli.setOptionGroup(opt, GROUP);
+                return opt;
+            })())
+                .addOption((() => {
+                const opt = plugin.createPluginDynamicOption(cli, '-r, --root-path <string>', (_bag, cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.rootPath || './')})`);
+                cli.setOptionGroup(opt, GROUP);
+                return opt;
+            })())
+                .addOption((() => {
+                const opt = plugin.createPluginDynamicOption(cli, '-g, --globs <string>', (_bag, cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.globs || '*')})`);
+                cli.setOptionGroup(opt, 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')
+                .argument('[command...]')
+                .addCommand(new Command()
+                .name('cmd')
+                .description('execute command, conflicts with --command option (default subcommand)')
+                .enablePositionalOptions()
+                .passThroughOptions()
+                .argument('[command...]')
+                .action(buildDefaultCmdAction(plugin, cli, batchCmd, opts)), { isDefault: true })
+                .action(buildParentAction(plugin, cli, opts));
+        },
+    });
+    return plugin;
+};
 
 export { batchPlugin };