@karmaniverous/get-dotenv 4.5.2 → 5.0.0-0

package/dist/plugins-batch.mjs

@@ -0,0 +1,567 @@
+import { Command } from 'commander';
+import { globby } from 'globby';
+import { packageDirectory } from 'package-directory';
+import path from 'path';
+import { execa, execaCommand } from 'execa';
+import { z } from 'zod';
+
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
+};
+
+// Minimal tokenizer for shell-off execution:
+// Splits by whitespace while preserving quoted segments (single or double quotes).
+const tokenize = (command) => {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command.charAt(i);
+        if (quote) {
+            if (c === quote) {
+                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
+                // "" -> " and '' -> '
+                const next = command.charAt(i + 1);
+                if (next === quote) {
+                    cur += quote;
+                    i += 1; // skip the second quote
+                }
+                else {
+                    // end of quoted segment
+                    quote = null;
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+        else {
+            if (c === '"' || c === "'") {
+                quote = c;
+            }
+            else if (/\s/.test(c)) {
+                if (cur) {
+                    out.push(cur);
+                    cur = '';
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+};
+
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:run]', ...args);
+    }
+};
+// Strip repeated symmetric outer quotes (single or double) until stable.
+// 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.
+const stripOuterQuotes = (s) => {
+    let out = s;
+    // Repeatedly trim only when the entire string is wrapped in matching quotes.
+    // Stop as soon as the ends are asymmetric or no quotes remain.
+    while (out.length >= 2) {
+        const a = out.charAt(0);
+        const b = out.charAt(out.length - 1);
+        const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+        if (!symmetric)
+            break;
+        out = out.slice(1, -1);
+    }
+    return out;
+};
+// Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
+// expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
+const sanitizeEnv = (env) => {
+    if (!env)
+        return undefined;
+    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) => {
+    if (shell === false) {
+        let file;
+        let args = [];
+        if (Array.isArray(command)) {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
+        else {
+            const tokens = tokenize(command);
+            file = tokens[0];
+            args = tokens.slice(1);
+        }
+        if (!file)
+            return 0;
+        dbg('exec (plain)', { file, args, stdio: opts.stdio });
+        // Build options without injecting undefined properties (exactOptionalPropertyTypes).
+        const envSan = sanitizeEnv(opts.env);
+        const plainOpts = {};
+        if (opts.cwd !== undefined)
+            plainOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            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 exit = result?.exitCode;
+        dbg('exit (plain)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+    else {
+        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        dbg('exec (shell)', {
+            shell: typeof shell === 'string' ? shell : 'custom',
+            stdio: opts.stdio,
+            command: commandStr,
+        });
+        const envSan = sanitizeEnv(opts.env);
+        const shellOpts = { shell };
+        if (opts.cwd !== undefined)
+            shellOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            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 exit = result?.exitCode;
+        dbg('exit (shell)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+};
+
+const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
+    let cwd = process.cwd();
+    if (pkgCwd) {
+        const pkgDir = await packageDirectory();
+        if (!pkgDir) {
+            logger.error('No package directory found.');
+            process.exit(0);
+        }
+        cwd = pkgDir;
+    }
+    const absRootPath = path.posix.join(cwd.split(path.sep).join(path.posix.sep), rootPath.split(path.sep).join(path.posix.sep));
+    const paths = await globby(globs.split(/\s+/), {
+        cwd: absRootPath,
+        expandDirectories: false,
+        onlyDirectories: true,
+        absolute: true,
+    });
+    if (!paths.length) {
+        logger.error(`No paths found for globs '${globs}' at '${absRootPath}'.`);
+        process.exit(0);
+    }
+    return { absRootPath, paths };
+};
+const execShellCommandBatch = async ({ command, getDotenvCliOptions, 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.
+    if (!command && !list) {
+        logger.error(`No command provided. Use --command or --list.`);
+        process.exit(0);
+    }
+    const { absRootPath, paths } = await globPaths({
+        globs,
+        logger,
+        rootPath,
+        // exactOptionalPropertyTypes: only include when defined
+        ...(pkgCwd !== undefined ? { pkgCwd } : {}),
+    });
+    const headerTitle = list
+        ? 'Listing working directories...'
+        : 'Executing command batch...';
+    logger.info('');
+    const headerRootPath = `ROOT:  ${absRootPath}`;
+    const headerGlobs = `GLOBS: ${globs}`;
+    // Prepare a safe label for the header (avoid undefined in template)
+    const commandLabel = Array.isArray(command)
+        ? command.join(' ')
+        : typeof command === 'string' && command.length > 0
+            ? command
+            : '';
+    const headerCommand = list ? `CMD:   (list only)` : `CMD:   ${commandLabel}`;
+    logger.info('*'.repeat(Math.max(headerTitle.length, headerRootPath.length, headerGlobs.length, headerCommand.length)));
+    logger.info(headerTitle);
+    logger.info('');
+    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;
+        }
+        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) {
+                await runCommand(command, shell, {
+                    cwd: path,
+                    env: {
+                        ...process.env,
+                        getDotenvCliOptions: getDotenvCliOptions
+                            ? JSON.stringify(getDotenvCliOptions)
+                            : undefined,
+                    },
+                    stdio: capture ? 'pipe' : 'inherit',
+                });
+            }
+            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);
+            }
+        }
+        catch (error) {
+            if (!ignoreErrors) {
+                throw error;
+            }
+        }
+    }
+    logger.info('');
+};
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+/**
+ * Resolve a command string from the {@link Scripts} table.
+ * A script may be expressed as a string or an object with a `cmd` property.
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
+ */
+const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
+    ? scripts[command].cmd
+    : (scripts?.[command] ?? command);
+/**
+ * Resolve the shell setting for a given command:
+ * - If the script entry is an object, prefer its `shell` override.
+ * - Otherwise use the provided `shell` (string | boolean).
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @param shell - Global shell preference (string | boolean).
+ */
+const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
+    ? (scripts[command].shell ?? false)
+    : (shell ?? false);
+
+/**
+ * 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 loggerLocal = opts.logger ?? console;
+    // Guard: when invoked without positional args (e.g., `batch --list`),
+    // defer entirely to the parent action handler.
+    const argsRaw = Array.isArray(commandParts)
+        ? commandParts
+        : [];
+    const localList = argsRaw.includes('-l') || argsRaw.includes('--list');
+    const args = localList
+        ? 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 || {});
+    // Resolve batch flags from the captured parent (batch) command.
+    const raw = batchCmd.opts();
+    const listFromParent = !!raw.list;
+    const ignoreErrors = !!raw.ignoreErrors;
+    const globs = typeof raw.globs === 'string' ? raw.globs : (cfg.globs ?? '*');
+    const pkgCwd = raw.pkgCwd !== undefined ? !!raw.pkgCwd : !!cfg.pkgCwd;
+    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : (cfg.rootPath ?? './');
+    // Resolve scripts/shell with precedence:
+    // plugin opts → plugin config → merged root CLI options
+    const mergedBag = ((batchCmd.parent ?? null)?.getDotenvCliOptions ?? {});
+    const scripts = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
+    const shell = opts.shell ?? cfg.shell ?? mergedBag.shell;
+    // If no positional args were given, bridge to --command/--list paths here.
+    if (args.length === 0) {
+        const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
+        if (typeof commandOpt === 'string') {
+            await execShellCommandBatch({
+                command: resolveCommand(scripts, commandOpt),
+                globs,
+                ignoreErrors,
+                list: false,
+                logger: loggerLocal,
+                ...(pkgCwd ? { pkgCwd } : {}),
+                rootPath,
+                shell: resolveShell(scripts, commandOpt, shell),
+            });
+            return;
+        }
+        if (raw.list || localList) {
+            await execShellCommandBatch({
+                globs,
+                ignoreErrors,
+                list: true,
+                logger: loggerLocal,
+                ...(pkgCwd ? { pkgCwd } : {}),
+                rootPath,
+                shell: (shell ?? false),
+            });
+            return;
+        }
+        {
+            const lr = loggerLocal;
+            const emit = lr.error ?? lr.log;
+            emit(`No command provided. Use --command or --list.`);
+        }
+        process.exit(0);
+    }
+    // If a local list flag was supplied with positional tokens (and no --command),
+    // treat tokens as additional globs and execute list mode.
+    if (localList && typeof raw.command !== 'string') {
+        const extraGlobs = args.map(String).join(' ').trim();
+        const mergedGlobs = [globs, extraGlobs].filter(Boolean).join(' ');
+        const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
+        await execShellCommandBatch({
+            globs: mergedGlobs,
+            ignoreErrors,
+            list: true,
+            logger: loggerLocal,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: (shell ?? shellBag.shell ?? false),
+        });
+        return;
+    }
+    // If parent list flag is set and positional tokens are present (and no --command),
+    // treat tokens as additional globs for list-only mode.
+    if (listFromParent && args.length > 0 && typeof raw.command !== 'string') {
+        const extra = args.map(String).join(' ').trim();
+        const mergedGlobs = [globs, extra].filter(Boolean).join(' ');
+        const mergedBag2 = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
+        await execShellCommandBatch({
+            globs: mergedGlobs,
+            ignoreErrors,
+            list: true,
+            logger: loggerLocal,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: (shell ?? mergedBag2.shell ?? false),
+        });
+        return;
+    }
+    // Join positional args as the command to execute.
+    const input = args.map(String).join(' ');
+    // Optional: round-trip parent merged options if present (shipped CLI).
+    const envBag = (batchCmd.parent ?? undefined)?.getDotenvCliOptions;
+    const mergedExec = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
+    const scriptsExec = scripts ?? mergedExec.scripts;
+    const shellExec = shell ?? mergedExec.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.
+    let commandArg = resolved;
+    if (shellSetting === false && resolved === input) {
+        const first = (args[0] ?? '').toLowerCase();
+        const hasEval = args.includes('-e') || args.includes('--eval');
+        if (first === 'node' && hasEval) {
+            commandArg = args.map(String);
+        }
+    }
+    await execShellCommandBatch({
+        command: commandArg,
+        ...(envBag ? { getDotenvCliOptions: envBag } : {}),
+        globs,
+        ignoreErrors,
+        list: false,
+        logger: loggerLocal,
+        ...(pkgCwd ? { pkgCwd } : {}),
+        rootPath,
+        shell: shellSetting,
+    });
+};
+
+/**
+ * Build the parent "batch" action handler (no explicit subcommand).
+ */
+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 cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
+    const cfg = (cfgRaw || {});
+    const raw = thisCommand.opts();
+    const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
+    const ignoreErrors = !!raw.ignoreErrors;
+    let globs = typeof raw.globs === 'string' ? raw.globs : (cfg.globs ?? '*');
+    const list = !!raw.list;
+    const pkgCwd = raw.pkgCwd !== undefined ? !!raw.pkgCwd : !!cfg.pkgCwd;
+    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : (cfg.rootPath ?? './');
+    // Treat parent positional tokens as the command when no explicit 'cmd' is used.
+    const argsParent = Array.isArray(commandParts) ? commandParts : [];
+    if (argsParent.length > 0 && !list) {
+        const input = argsParent.map(String).join(' ');
+        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        const scriptsAll = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
+        const shellAll = opts.shell ?? cfg.shell ?? mergedBag.shell;
+        const resolved = resolveCommand(scriptsAll, input);
+        const shellSetting = resolveShell(scriptsAll, input, shellAll);
+        // Parent path: pass a string; executor handles shell-specific details.
+        const commandArg = resolved;
+        await execShellCommandBatch({
+            command: commandArg,
+            globs,
+            ignoreErrors,
+            list: false,
+            logger,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: shellSetting,
+        });
+        return;
+    }
+    // List-only: merge extra positional tokens into globs when no --command is present.
+    if (list && argsParent.length > 0 && !commandOpt) {
+        const extra = argsParent.map(String).join(' ').trim();
+        if (extra.length > 0)
+            globs = [globs, extra].filter(Boolean).join(' ');
+        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        await execShellCommandBatch({
+            globs,
+            ignoreErrors,
+            list: true,
+            logger,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false),
+        });
+        return;
+    }
+    if (!commandOpt && !list) {
+        logger.error(`No command provided. Use --command or --list.`);
+        process.exit(0);
+    }
+    if (typeof commandOpt === 'string') {
+        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        const scriptsOpt = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
+        const shellOpt = opts.shell ?? cfg.shell ?? mergedBag.shell;
+        await execShellCommandBatch({
+            command: resolveCommand(scriptsOpt, commandOpt),
+            globs,
+            ignoreErrors,
+            list,
+            logger,
+            ...(pkgCwd ? { pkgCwd } : {}),
+            rootPath,
+            shell: resolveShell(scriptsOpt, commandOpt, shellOpt),
+        });
+        return;
+    }
+    // list only (explicit --list without --command)
+    const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+    const shellOnly = (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false);
+    await execShellCommandBatch({
+        globs,
+        ignoreErrors,
+        list: true,
+        logger,
+        ...(pkgCwd ? { pkgCwd } : {}),
+        rootPath,
+        shell: (shellOnly ?? false),
+    });
+};
+
+// Per-plugin config schema (optional fields; used as defaults).
+const ScriptSchema = z.union([
+    z.string(),
+    z.object({
+        cmd: z.string(),
+        shell: z.union([z.string(), z.boolean()]).optional(),
+    }),
+]);
+const BatchConfigSchema = z.object({
+    scripts: z.record(z.string(), ScriptSchema).optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    rootPath: z.string().optional(),
+    globs: z.string().optional(),
+    pkgCwd: z.boolean().optional(),
+});
+
+/**
+ * Batch plugin for the GetDotenv CLI host.
+ *
+ * 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));
+    },
+});
+
+export { batchPlugin };