@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/plugins-demo.cjs

@@ -1,352 +0,0 @@
-'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;
-    }
-};
-
-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;
-};
-
-/** 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;
-};
-
-/**
- * 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);
-
-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: buildSpawnEnv(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: buildSpawnEnv(process.env, dotenv),
-                stdio: 'inherit',
-            });
-        });
-    },
-    /**
-     * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
-     * For the demo we emit a single breadcrumb only when GETDOTENV_DEBUG is set,
-     * keeping default runs (tests/CI/smoke) quiet.
-     */
-    afterResolve(_cli, ctx) {
-        if (process.env.GETDOTENV_DEBUG) {
-            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

@@ -1,158 +0,0 @@
-import { Command } from 'commander';
-import { ZodType } from 'zod';
-
-/**
- * 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;
-}
-
-/** 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.
- */
-
-/**
- * Structural public interface for the host exposed to plugins.
- * - Extends Commander.Command so plugins can attach options/commands/hooks.
- * - Adds host-specific helpers used by built-in plugins.
- *
- * Purpose: remove nominal class identity (private fields) from the plugin seam
- * to avoid TS2379 under exactOptionalPropertyTypes in downstream consumers.
- */
-type GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> = Command & {
-    ns: (name: string) => Command;
-    getCtx: () => GetDotenvCliCtx<TOptions> | undefined;
-    resolveAndLoad: (customOptions?: Partial<TOptions>) => Promise<GetDotenvCliCtx<TOptions>>;
-};
-/** 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: GetDotenvCliPublic) => 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: GetDotenvCliPublic, 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;
-}
-
-/** * 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 demoPlugin: () => GetDotenvCliPlugin;
-
-export { demoPlugin };

package/dist/plugins-demo.d.mts

@@ -1,158 +0,0 @@
-import { Command } from 'commander';
-import { ZodType } from 'zod';
-
-/**
- * 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;
-}
-
-/** 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.
- */
-
-/**
- * Structural public interface for the host exposed to plugins.
- * - Extends Commander.Command so plugins can attach options/commands/hooks.
- * - Adds host-specific helpers used by built-in plugins.
- *
- * Purpose: remove nominal class identity (private fields) from the plugin seam
- * to avoid TS2379 under exactOptionalPropertyTypes in downstream consumers.
- */
-type GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> = Command & {
-    ns: (name: string) => Command;
-    getCtx: () => GetDotenvCliCtx<TOptions> | undefined;
-    resolveAndLoad: (customOptions?: Partial<TOptions>) => Promise<GetDotenvCliCtx<TOptions>>;
-};
-/** 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: GetDotenvCliPublic) => 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: GetDotenvCliPublic, 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;
-}
-
-/** * 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 demoPlugin: () => GetDotenvCliPlugin;
-
-export { demoPlugin };