@karmaniverous/get-dotenv 5.2.0 → 5.2.2

package/dist/plugins-cmd.d.ts

@@ -0,0 +1,311 @@
+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;
+}
+
+type CmdPluginOptions = {
+    /**
+     * When true, register as the default subcommand at the root.   */
+    asDefault?: boolean;
+    /**
+     * Optional alias option attached to the parent command to invoke the cmd   * behavior without specifying the subcommand explicitly.
+     */
+    optionAlias?: string | {
+        flags: string;
+        description?: string;
+        expand?: boolean;
+    };
+};
+/**+ Cmd plugin: executes a command using the current getdotenv CLI context.
+ *
+ * - Joins positional args into a single command string.
+ * - Resolves scripts and shell settings using shared helpers.
+ * - Forwards merged CLI options to subprocesses via
+ *   process.env.getDotenvCliOptions for nested CLI behavior. */
+declare const cmdPlugin: (options?: CmdPluginOptions) => GetDotenvCliPlugin;
+
+export { cmdPlugin };
+export type { CmdPluginOptions };