@karmaniverous/get-dotenv 5.2.2 → 5.2.4

package/dist/plugins.d.cts

@@ -0,0 +1,210 @@
+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;
+}
+
+/** * 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>;
+};
+
+/** 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;
+}
+
+declare const awsPlugin: () => GetDotenvCliPlugin;
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean | undefined;
+}>;
+
+type BatchPluginOptions = {
+    scripts?: Scripts;
+    shell?: string | boolean;
+    logger?: Logger;
+};
+
+/**
+ * Batch plugin for the GetDotenv CLI host.
+ *
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * - scripts/shell: used to resolve command and shell behavior per script or global default.
+ * - logger: defaults to console.
+ */
+declare const batchPlugin: (opts?: BatchPluginOptions) => 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;
+
+declare const demoPlugin: () => GetDotenvCliPlugin;
+
+type InitPluginOptions = {
+    logger?: Logger;
+};
+declare const initPlugin: (opts?: InitPluginOptions) => GetDotenvCliPlugin;
+
+export { awsPlugin, batchPlugin, cmdPlugin, demoPlugin, initPlugin };

package/dist/plugins.d.mts

@@ -0,0 +1,210 @@
+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;
+}
+
+/** * 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>;
+};
+
+/** 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;
+}
+
+declare const awsPlugin: () => GetDotenvCliPlugin;
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean | undefined;
+}>;
+
+type BatchPluginOptions = {
+    scripts?: Scripts;
+    shell?: string | boolean;
+    logger?: Logger;
+};
+
+/**
+ * Batch plugin for the GetDotenv CLI host.
+ *
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * - scripts/shell: used to resolve command and shell behavior per script or global default.
+ * - logger: defaults to console.
+ */
+declare const batchPlugin: (opts?: BatchPluginOptions) => 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;
+
+declare const demoPlugin: () => GetDotenvCliPlugin;
+
+type InitPluginOptions = {
+    logger?: Logger;
+};
+declare const initPlugin: (opts?: InitPluginOptions) => GetDotenvCliPlugin;
+
+export { awsPlugin, batchPlugin, cmdPlugin, demoPlugin, initPlugin };

package/dist/plugins.d.ts

@@ -0,0 +1,210 @@
+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;
+}
+
+/** * 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>;
+};
+
+/** 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;
+}
+
+declare const awsPlugin: () => GetDotenvCliPlugin;
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean | undefined;
+}>;
+
+type BatchPluginOptions = {
+    scripts?: Scripts;
+    shell?: string | boolean;
+    logger?: Logger;
+};
+
+/**
+ * Batch plugin for the GetDotenv CLI host.
+ *
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * - scripts/shell: used to resolve command and shell behavior per script or global default.
+ * - logger: defaults to console.
+ */
+declare const batchPlugin: (opts?: BatchPluginOptions) => 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;
+
+declare const demoPlugin: () => GetDotenvCliPlugin;
+
+type InitPluginOptions = {
+    logger?: Logger;
+};
+declare const initPlugin: (opts?: InitPluginOptions) => GetDotenvCliPlugin;
+
+export { awsPlugin, batchPlugin, cmdPlugin, demoPlugin, initPlugin };