@karmaniverous/get-dotenv 4.6.0-0 → 5.0.0-0

package/dist/cliHost.d.cts

@@ -0,0 +1,193 @@
+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;
+}
+
+/** * 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>;
+};
+/**
+ * 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 {
+    /** Registered top-level plugins (composition happens via .use()) */
+    private _plugins;
+    /** One-time installation guard */
+    private _installed;
+    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;
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name: string): Command;
+    /**
+     * 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;
+}
+/**
+ * Public spec type for defining a plugin with optional children.
+ * Exported to ensure TypeDoc links and navigation resolve correctly.
+ */
+type DefineSpec = Omit<GetDotenvCliPlugin, 'children' | 'use'> & {
+    children?: GetDotenvCliPlugin[];
+};
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
+
+export { GetDotenvCli, definePlugin };
+export type { DefineSpec, GetDotenvCliPlugin };

package/dist/cliHost.d.mts

@@ -0,0 +1,193 @@
+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;
+}
+
+/** * 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>;
+};
+/**
+ * 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 {
+    /** Registered top-level plugins (composition happens via .use()) */
+    private _plugins;
+    /** One-time installation guard */
+    private _installed;
+    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;
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name: string): Command;
+    /**
+     * 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;
+}
+/**
+ * Public spec type for defining a plugin with optional children.
+ * Exported to ensure TypeDoc links and navigation resolve correctly.
+ */
+type DefineSpec = Omit<GetDotenvCliPlugin, 'children' | 'use'> & {
+    children?: GetDotenvCliPlugin[];
+};
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
+
+export { GetDotenvCli, definePlugin };
+export type { DefineSpec, GetDotenvCliPlugin };

package/dist/cliHost.d.ts

@@ -0,0 +1,193 @@
+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;
+}
+
+/** * 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>;
+};
+/**
+ * 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 {
+    /** Registered top-level plugins (composition happens via .use()) */
+    private _plugins;
+    /** One-time installation guard */
+    private _installed;
+    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;
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name: string): Command;
+    /**
+     * 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;
+}
+/**
+ * Public spec type for defining a plugin with optional children.
+ * Exported to ensure TypeDoc links and navigation resolve correctly.
+ */
+type DefineSpec = Omit<GetDotenvCliPlugin, 'children' | 'use'> & {
+    children?: GetDotenvCliPlugin[];
+};
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
+
+export { GetDotenvCli, definePlugin };
+export type { DefineSpec, GetDotenvCliPlugin };