@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

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 };

package/dist/plugins-init.cjs

@@ -1,289 +0,0 @@
-'use strict';
-
-var node_process = require('node:process');
-var fs = require('fs-extra');
-var path = require('path');
-var promises = require('readline/promises');
-
-/** 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;
-};
-
-const ensureDir = async (p) => {
-    await fs.ensureDir(p);
-    return p;
-};
-const writeFile = async (dest, data) => {
-    await ensureDir(path.dirname(dest));
-    await fs.writeFile(dest, data, 'utf-8');
-};
-const copyTextFile = async (src, dest, substitutions) => {
-    const contents = await fs.readFile(src, 'utf-8');
-    const out = substitutions && Object.keys(substitutions).length > 0
-        ? Object.entries(substitutions).reduce((acc, [k, v]) => acc.split(k).join(v), contents)
-        : contents;
-    await writeFile(dest, out);
-};
-/**
- * Ensure a set of lines exist (exact match) in a file. Creates the file
- * when missing. Returns whether it was created or changed.
- */
-const ensureLines = async (filePath, lines) => {
-    const exists = await fs.pathExists(filePath);
-    const current = exists ? await fs.readFile(filePath, 'utf-8') : '';
-    const curLines = current.split(/\r?\n/);
-    const have = new Set(curLines.filter((l) => l.length > 0));
-    let mutated = false;
-    for (const l of lines) {
-        if (!have.has(l)) {
-            curLines.push(l);
-            have.add(l);
-            mutated = true;
-        }
-    }
-    // Normalize to LF and ensure trailing newline
-    const next = curLines.filter((l) => l.length > 0).join('\n') + '\n';
-    if (!exists) {
-        await writeFile(filePath, next);
-        return { created: true, changed: true };
-    }
-    if (mutated) {
-        await fs.writeFile(filePath, next, 'utf-8');
-        return { created: false, changed: true };
-    }
-    return { created: false, changed: false };
-};
-
-// Templates root used by the scaffolder
-const TEMPLATES_ROOT = path.resolve('templates');
-
-const planConfigCopies = ({ format, withLocal, destRoot, }) => {
-    const copies = [];
-    if (format === 'json') {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'json', 'public', 'getdotenv.config.json'),
-            dest: path.join(destRoot, 'getdotenv.config.json'),
-        });
-        if (withLocal) {
-            copies.push({
-                src: path.join(TEMPLATES_ROOT, 'config', 'json', 'local', 'getdotenv.config.local.json'),
-                dest: path.join(destRoot, 'getdotenv.config.local.json'),
-            });
-        }
-    }
-    else if (format === 'yaml') {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'public', 'getdotenv.config.yaml'),
-            dest: path.join(destRoot, 'getdotenv.config.yaml'),
-        });
-        if (withLocal) {
-            copies.push({
-                src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'local', 'getdotenv.config.local.yaml'),
-                dest: path.join(destRoot, 'getdotenv.config.local.yaml'),
-            });
-        }
-    }
-    else if (format === 'js') {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'js', 'getdotenv.config.js'),
-            dest: path.join(destRoot, 'getdotenv.config.js'),
-        });
-    }
-    else {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'ts', 'getdotenv.config.ts'),
-            dest: path.join(destRoot, 'getdotenv.config.ts'),
-        });
-    }
-    return copies;
-};
-const planCliCopies = ({ cliName, destRoot, }) => {
-    const subs = { __CLI_NAME__: cliName };
-    const base = path.join(destRoot, 'src', 'cli', cliName);
-    return [
-        {
-            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'index.ts'),
-            dest: path.join(base, 'index.ts'),
-            subs,
-        },
-        {
-            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'plugins', 'hello.ts'),
-            dest: path.join(base, 'plugins', 'hello.ts'),
-            subs,
-        },
-    ];
-};
-
-/**
- * Determine whether the current environment should be treated as non-interactive.
- * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
- */
-const isNonInteractive = () => {
-    const ciLike = process.env.CI ||
-        process.env.GITHUB_ACTIONS ||
-        process.env.BUILDKITE ||
-        process.env.TEAMCITY_VERSION ||
-        process.env.TF_BUILD;
-    return Boolean(ciLike) || !(node_process.stdin.isTTY && node_process.stdout.isTTY);
-};
-const promptDecision = async (filePath, logger, rl) => {
-    logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    while (true) {
-        const a = (await rl.question('> ')).trim();
-        const valid = ['o', 'e', 's', 'O', 'E', 'S'];
-        if (valid.includes(a))
-            return a;
-        logger.log('Please enter one of: o e s O E S');
-    }
-};
-
-/**
- * Requirements: Init scaffolding plugin with collision flow and CI detection.
- * Note: Large file scheduled for decomposition; tracked in stan.todo.md.
- */
-const initPlugin = (opts = {}) => definePlugin({
-    id: 'init',
-    setup(cli) {
-        const logger = opts.logger ?? console;
-        const cmd = cli
-            .ns('init')
-            .description('Scaffold getdotenv config files and a host-based CLI skeleton.')
-            .argument('[dest]', 'destination path (default: ./)', '.')
-            .option('--config-format <format>', 'config format: json|yaml|js|ts', 'json')
-            .option('--with-local', 'include .local config variant')
-            .option('--dynamic', 'include dynamic examples (JS/TS configs)')
-            .option('--cli-name <string>', 'CLI name for skeleton and tokens')
-            .option('--force', 'overwrite all existing files')
-            .option('--yes', 'skip all collisions (no overwrite)')
-            .action(async (destArg) => {
-            // Read options directly from the captured command instance.
-            // Cast to a plain record to satisfy exact-optional and lint safety.
-            const o = cmd.opts() ?? {};
-            const destRel = typeof destArg === 'string' && destArg.length > 0 ? destArg : '.';
-            const cwd = process.cwd();
-            const destRoot = path.resolve(cwd, destRel);
-            const formatInput = o.configFormat;
-            const formatRaw = typeof formatInput === 'string'
-                ? formatInput.toLowerCase()
-                : 'json';
-            const format = (['json', 'yaml', 'js', 'ts'].includes(formatRaw)
-                ? formatRaw
-                : 'json');
-            const withLocal = !!o.withLocal;
-            // dynamic flag reserved for future template variants; present for UX compatibility
-            void o.dynamic;
-            // CLI name default: --cli-name | basename(dest) | 'mycli'
-            const cliName = (typeof o.cliName === 'string' && o.cliName.length > 0
-                ? o.cliName
-                : path.basename(destRoot) || 'mycli') || 'mycli';
-            // Precedence: --force > --yes > auto-detect(non-interactive => yes)
-            const force = !!o.force;
-            const yes = !!o.yes || (!force && isNonInteractive());
-            // Build copy plan
-            const cfgCopies = planConfigCopies({ format, withLocal, destRoot });
-            const cliCopies = planCliCopies({ cliName, destRoot });
-            const copies = [...cfgCopies, ...cliCopies];
-            // Interactive state
-            let globalDecision;
-            const rl = promises.createInterface({ input: node_process.stdin, output: node_process.stdout });
-            try {
-                for (const item of copies) {
-                    const exists = await fs.pathExists(item.dest);
-                    if (!exists) {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Created ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    // Collision
-                    if (force) {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    if (yes) {
-                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    let decision = globalDecision;
-                    if (!decision) {
-                        const a = await promptDecision(item.dest, logger, rl);
-                        if (a === 'O') {
-                            globalDecision = 'overwrite';
-                            decision = 'overwrite';
-                        }
-                        else if (a === 'E') {
-                            globalDecision = 'example';
-                            decision = 'example';
-                        }
-                        else if (a === 'S') {
-                            globalDecision = 'skip';
-                            decision = 'skip';
-                        }
-                        else {
-                            decision =
-                                a === 'o' ? 'overwrite' : a === 'e' ? 'example' : 'skip';
-                        }
-                    }
-                    if (decision === 'overwrite') {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
-                    }
-                    else if (decision === 'example') {
-                        const destEx = `${item.dest}.example`;
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, destEx, subs);
-                        logger.log(`Wrote example ${path.relative(cwd, destEx)}`);
-                    }
-                    else {
-                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
-                    }
-                }
-                // Ensure .gitignore includes local config patterns.
-                const giPath = path.join(destRoot, '.gitignore');
-                const { created, changed } = await ensureLines(giPath, [
-                    'getdotenv.config.local.*',
-                    '*.local',
-                ]);
-                if (created) {
-                    logger.log(`Created ${path.relative(cwd, giPath)}`);
-                }
-                else if (changed) {
-                    logger.log(`Updated ${path.relative(cwd, giPath)}`);
-                }
-            }
-            finally {
-                rl.close();
-            }
-        });
-    },
-});
-
-exports.initPlugin = initPlugin;