@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/plugins-batch.cjs

@@ -1,616 +0,0 @@
-'use strict';
-
-var commander = require('commander');
-var globby = require('globby');
-var packageDirectory = require('package-directory');
-var path = require('path');
-var execa = require('execa');
-var zod = require('zod');
-
-/** src/cliHost/definePlugin.ts
- * Plugin contracts for the GetDotenv CLI host.
- *
- * This module exposes a structural public interface for the host that plugins
- * 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) => {
-    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.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 execa.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 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) => {
-    const raw = {
-        ...(base ?? {}),
-        ...(overlay ?? {}),
-    };
-    // Drop undefined first
-    const entries = Object.entries(dropUndefined(raw));
-    if (process.platform === 'win32') {
-        // Windows: keys are case-insensitive; collapse duplicates
-        const byLower = new Map();
-        for (const [k, v] of entries) {
-            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
-        }
-        const out = {};
-        for (const [, [k, v]] of byLower)
-            out[k] = v;
-        // HOME fallback from USERPROFILE (common expectation)
-        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
-            const up = out['USERPROFILE'];
-            if (typeof up === 'string' && up.length > 0)
-                out['HOME'] = up;
-        }
-        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
-        const tmp = out['TMP'] ?? out['TEMP'];
-        if (typeof tmp === 'string' && tmp.length > 0) {
-            out['TMP'] = tmp;
-            out['TEMP'] = tmp;
-        }
-        return out;
-    }
-    // POSIX: keep keys as-is
-    const out = Object.fromEntries(entries);
-    // Ensure TMPDIR exists when any temp key is present (best-effort)
-    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
-    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
-        out['TMPDIR'] = tmpdir;
-    }
-    return out;
-};
-
-const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
-    let cwd = process.cwd();
-    if (pkgCwd) {
-        const pkgDir = await packageDirectory.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.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) {
-                const envBag = getDotenvCliOptions !== undefined
-                    ? { getDotenvCliOptions: JSON.stringify(getDotenvCliOptions) }
-                    : undefined;
-                await runCommand(command, shell, {
-                    cwd: path,
-                    env: buildSpawnEnv(process.env, envBag),
-                    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 = zod.z.union([
-    zod.z.string(),
-    zod.z.object({
-        cmd: zod.z.string(),
-        shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
-    }),
-]);
-const BatchConfigSchema = zod.z.object({
-    scripts: zod.z.record(zod.z.string(), ScriptSchema).optional(),
-    shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
-    rootPath: zod.z.string().optional(),
-    globs: zod.z.string().optional(),
-    pkgCwd: zod.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 commander.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));
-    },
-});
-
-exports.batchPlugin = batchPlugin;