@karmaniverous/get-dotenv 5.2.0 → 5.2.2

package/dist/plugins-demo.cjs

@@ -0,0 +1,330 @@
+'use strict';
+
+var execa = require('execa');
+
+// 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;
+    }
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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);
+
+/**
+ * Demo plugin (educational).
+ *
+ * Purpose
+ * - Showcase how to build a plugin for the GetDotenv CLI host.
+ * - Demonstrate:
+ *   - Accessing the resolved dotenv context (ctx).
+ *   - Executing child processes with explicit env injection.
+ *   - Resolving commands via scripts and honoring per-script shell overrides.
+ *   - Thin adapters: business logic stays minimal; use shared helpers.
+ *
+ * Key host APIs used:
+ * - definePlugin: declare a plugin with setup and optional afterResolve.
+ * - cli.ns(name): create a namespaced subcommand under the root CLI.
+ * - cli.getCtx(): access \{ optionsResolved, dotenv, plugins?, pluginConfigs? \}.
+ *
+ * Design notes
+ * - We use the shared runCommand() helper so behavior matches the built-in
+ *   cmd/batch plugins (env sanitization, plain vs shell execution, stdio).
+ * - We inject ctx.dotenv into child env explicitly to avoid bleeding prior
+ *   secrets from process.env when exclusions are set (e.g., --exclude-private).
+ * - We resolve scripts and shell using shared helpers to honor overrides:
+ *   resolveCommand(scripts, input) and resolveShell(scripts, input, shell).
+ *
+ * Usage (examples)
+ *   getdotenv demo ctx
+ *   getdotenv demo run --print APP_SETTING
+ *   getdotenv demo script echo OK
+ *   getdotenv --trace demo run --print ENV_SETTING
+ */
+const demoPlugin = () => definePlugin({
+    id: 'demo',
+    setup(cli) {
+        const logger = console;
+        const ns = cli
+            .ns('demo')
+            .description('Educational demo of host/plugin features (context, child exec, scripts/shell)');
+        /**
+         * demo ctx
+         * Print a summary of the current dotenv context.
+         *
+         * Notes:
+         * - The host resolves context once per invocation in a preSubcommand hook
+         *   (added by enhanceGetDotenvCli.passOptions() in the shipped CLI).
+         * - ctx.dotenv contains the final merged values after overlays/dynamics.
+         */
+        ns.command('ctx')
+            .description('Print a summary of the current dotenv context')
+            .action(() => {
+            const ctx = cli.getCtx();
+            const dotenv = ctx?.dotenv ?? {};
+            const keys = Object.keys(dotenv).sort();
+            const sample = keys.slice(0, 5);
+            logger.log('[demo] Context summary:');
+            logger.log(`- keys: ${keys.length.toString()}`);
+            logger.log(`- sample keys: ${sample.join(', ') || '(none)'}`);
+            logger.log('- tip: use "--trace [keys...]" for per-key diagnostics');
+        });
+        /**
+         * demo run [--print KEY]
+         * Execute a small child process that prints a dotenv value.
+         *
+         * Design:
+         * - Use shell-off + argv array to avoid cross-platform quoting pitfalls.
+         * - Inject ctx.dotenv explicitly into the child env.
+         * - Inherit stdio so output streams live (works well outside CI).
+         *
+         * Tip:
+         * - For deterministic capture in CI, run with "--capture" (or set
+         *   GETDOTENV_STDIO=pipe). The shipped CLI honors both.
+         */
+        ns.command('run')
+            .description('Run a small child process under the current dotenv (shell-off)')
+            .option('--print <key>', 'dotenv key to print', 'APP_SETTING')
+            .action(async (opts) => {
+            const key = typeof opts.print === 'string' && opts.print.length > 0
+                ? opts.print
+                : 'APP_SETTING';
+            // Build a minimal node -e payload via argv array (avoid quoting issues).
+            const code = `console.log(process.env.${key} ?? "")`;
+            const ctx = cli.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            // Inherit stdio for an interactive demo. Use --capture for CI.
+            await runCommand(['node', '-e', code], false, {
+                env: { ...process.env, ...dotenv },
+                stdio: 'inherit',
+            });
+        });
+        /**
+         * demo script [command...]
+         * Resolve and execute a command using the current scripts table and
+         * shell preference (with per-script overrides).
+         *
+         * How it works:
+         * - We read the merged CLI options persisted by the shipped CLI’s
+         *   passOptions() hook on the current command instance’s parent.
+         * - resolveCommand resolves a script name → cmd or passes through a raw
+         *   command string.
+         * - resolveShell chooses the appropriate shell:
+         *    scripts[name].shell ?? global shell (string|boolean).
+         */
+        ns.command('script')
+            .description('Resolve a command via scripts and execute it with the proper shell')
+            .argument('[command...]')
+            .action(async (commandParts, _opts, thisCommand) => {
+            // Safely access the parent’s merged options (installed by passOptions()).
+            const parent = thisCommand.parent;
+            const bag = (parent?.getDotenvCliOptions ?? {});
+            const input = Array.isArray(commandParts)
+                ? commandParts.map(String).join(' ')
+                : '';
+            if (!input) {
+                logger.log('[demo] Please provide a command or script name, e.g. "echo OK" or "git-status".');
+                return;
+            }
+            const resolved = resolveCommand(bag?.scripts, input);
+            const shell = resolveShell(bag?.scripts, input, bag?.shell);
+            // Compose child env (parent + ctx.dotenv). This mirrors cmd/batch behavior.
+            const ctx = cli.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            await runCommand(resolved, shell, {
+                env: { ...process.env, ...dotenv },
+                stdio: 'inherit',
+            });
+        });
+    },
+    /**
+     * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
+     * For the demo we just log once to hint where such logic would live.
+     */
+    afterResolve(_cli, ctx) {
+        const keys = Object.keys(ctx.dotenv);
+        if (keys.length > 0) {
+            // Keep noise low; a single-line breadcrumb is sufficient for the demo.
+            console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+        }
+    },
+});
+
+exports.demoPlugin = demoPlugin;

package/dist/plugins-demo.d.cts

@@ -0,0 +1,291 @@
+import { ZodType } from 'zod';
+import { Command } from 'commander';
+
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
+/**
+ * Dynamic variable function signature. Receives the current expanded variables
+ * 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 GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
+type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
+/**
+ * Options passed programmatically to `getDotenv`.
+ */
+interface GetDotenvOptions {
+    /**
+     * default target environment (used if `env` is not provided)
+     */
+    defaultEnv?: string;
+    /**
+     * token indicating a dotenv file
+     */
+    dotenvToken: string;
+    /**
+     * path to JS/TS module default-exporting an object keyed to dynamic variable functions
+     */
+    dynamicPath?: string;
+    /**
+     * Programmatic dynamic variables map. When provided, this takes precedence
+     * over {@link GetDotenvOptions.dynamicPath}.
+     */
+    dynamic?: GetDotenvDynamic;
+    /**
+     * target environment
+     */
+    env?: string;
+    /**
+     * exclude dynamic variables from loading
+     */
+    excludeDynamic?: boolean;
+    /**
+     * exclude environment-specific variables from loading
+     */
+    excludeEnv?: boolean;
+    /**
+     * exclude global variables from loading
+     */
+    excludeGlobal?: boolean;
+    /**
+     * exclude private variables from loading
+     */
+    excludePrivate?: boolean;
+    /**
+     * exclude public variables from loading
+     */
+    excludePublic?: boolean;
+    /**
+     * load dotenv variables to `process.env`
+     */
+    loadProcess?: boolean;
+    /**
+     * log loaded dotenv variables to `logger`
+     */
+    log?: boolean;
+    /**
+     * logger object (defaults to console)
+     */
+    logger?: Logger;
+    /**
+     * if populated, writes consolidated dotenv file to this path (follows dotenvExpand rules)
+     */
+    outputPath?: string;
+    /**
+     * array of input directory paths
+     */
+    paths?: string[];
+    /**
+     * filename token indicating private variables
+     */
+    privateToken?: string;
+    /**
+     * explicit variables to include
+     */
+    vars?: ProcessEnv;
+    /**
+     * Reserved: config loader flag (no-op).
+     * The plugin-first host and generator paths already use the config
+     * loader/overlay pipeline unconditionally (no-op when no config files
+     * are present). This flag is accepted for forward compatibility but
+     * currently has no effect.
+     */
+    useConfigLoader?: boolean;
+}
+
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean;
+}>;
+/**
+ * Options passed programmatically to `getDotenvCli`.
+ */
+interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
+    /**
+     * Logs CLI internals when true.
+     */
+    debug?: boolean;
+    /**
+     * Strict mode: fail the run when env validation issues are detected
+     * (schema or requiredKeys). Warns by default when false or unset.
+     */
+    strict?: boolean;
+    /**
+     * Redaction (presentation): mask secret-like values in logs/trace.
+     */
+    redact?: boolean;
+    /**
+     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
+     */
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    /**
+     * When true, capture child stdout/stderr and re-emit after completion.
+     * Useful for tests/CI. Default behavior is streaming via stdio: 'inherit'.
+     */
+    capture?: boolean;
+    /**
+     * A delimited string of paths to dotenv files.
+     */
+    paths?: string;
+    /**
+     * A delimiter string with which to split `paths`. Only used if
+     * `pathsDelimiterPattern` is not provided.
+     */
+    pathsDelimiter?: string;
+    /**
+     * A regular expression pattern with which to split `paths`. Supersedes
+     * `pathsDelimiter`.
+     */
+    pathsDelimiterPattern?: string;
+    /**
+     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
+     */
+    scripts?: Scripts;
+    /**
+     * Determines how commands and scripts are executed. If `false` or
+     * `undefined`, commands are executed as plain Javascript using the default
+     * execa parser. If `true`, commands are executed using the default OS shell
+     * parser. Otherwise the user may provide a specific shell string (e.g.
+     * `/bin/bash`)
+     */
+    shell?: string | boolean;
+    /**
+     * A delimited string of key-value pairs declaratively specifying variables &
+     * values to be loaded in addition to any dotenv files.
+     */
+    vars?: string;
+    /**
+     * A string with which to split keys from values in `vars`. Only used if
+     * `varsDelimiterPattern` is not provided.
+     */
+    varsAssignor?: string;
+    /**
+     * A regular expression pattern with which to split variable names from values
+     * in `vars`. Supersedes `varsAssignor`.
+     */
+    varsAssignorPattern?: string;
+    /**
+     * A string with which to split `vars` into key-value pairs. Only used if
+     * `varsDelimiterPattern` is not provided.
+     */
+    varsDelimiter?: string;
+    /**
+     * A regular expression pattern with which to split `vars` into key-value
+     * pairs. Supersedes `varsDelimiter`.
+     */
+    varsDelimiterPattern?: string;
+}
+
+/** * 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>;
+};
+declare const HELP_HEADER_SYMBOL: unique symbol;
+/**
+ * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+ *
+ * Responsibilities:
+ * - Resolve options strictly and compute dotenv context (resolveAndLoad).
+ * - Expose a stable accessor for the current context (getCtx).
+ * - Provide a namespacing helper (ns).
+ * - Support composable plugins with parent → children install and afterResolve.
+ *
+ * NOTE: This host is additive and does not alter the legacy CLI.
+ */
+declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+    #private;
+    /** Registered top-level plugins (composition happens via .use()) */
+    private _plugins;
+    /** One-time installation guard */
+    private _installed;
+    /** Optional header line to prepend in help output */
+    private [HELP_HEADER_SYMBOL];
+    constructor(alias?: string);
+    /**
+     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     */
+    resolveAndLoad(customOptions?: Partial<TOptions>): Promise<GetDotenvCliCtx<TOptions>>;
+    /**
+     * Retrieve the current invocation context (if any).
+     */
+    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions(): GetDotenvCliOptions | undefined;
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag: GetDotenvCliOptions): void;
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name: string): Command;
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions<T>(fn: (root: Command) => T): T;
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    brand(args: {
+        name?: string;
+        description?: string;
+        version?: string;
+        importMetaUrl?: string;
+        helpHeader?: string;
+    }): Promise<this>;
+    /**
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
+     */
+    use(plugin: GetDotenvCliPlugin): this;
+    /**
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
+     */
+    install(): Promise<void>;
+    /**
+     * Run afterResolve hooks for all plugins (parent → children).
+     */
+    private _runAfterResolve;
+}
+
+/** Public plugin contract used by the GetDotenv CLI host. */ interface GetDotenvCliPlugin {
+    id?: string /**
+     * Setup phase: register commands and wiring on the provided CLI instance.   * Runs parent → children (pre-order).
+     */;
+    setup: (cli: GetDotenvCli) => void | Promise<void>;
+    /**
+     * 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).
+     */
+    afterResolve?: (cli: GetDotenvCli, ctx: GetDotenvCliCtx) => void | Promise<void>;
+    /**
+     * Optional Zod schema for this plugin's config slice (from config.plugins[id]).
+     * When provided, the host validates the merged config under the guarded loader path.
+     */
+    configSchema?: ZodType;
+    /**
+     * Compositional children. Installed after the parent per pre-order.
+     */ children: GetDotenvCliPlugin[];
+    /**
+     * Compose a child plugin. Returns the parent to enable chaining.
+     */
+    use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
+}
+
+declare const demoPlugin: () => GetDotenvCliPlugin;
+
+export { demoPlugin };