@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/plugins.d.ts

@@ -1,9 +1,39 @@
-import { Command } from 'commander';
-import { ZodType } from 'zod';
+import { z, ZodObject } from 'zod';
+import { Command, Option } from 'commander';
+
+/**
+ * Scripts table shape (configurable shell type).
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
+    cmd: string;
+    shell?: TShell | undefined;
+}>;
+
+declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: z.ZodOptional<z.ZodString>;
+    dotenvToken: z.ZodOptional<z.ZodString>;
+    dynamicPath: z.ZodOptional<z.ZodString>;
+    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    env: z.ZodOptional<z.ZodString>;
+    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
+    excludeEnv: z.ZodOptional<z.ZodBoolean>;
+    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
+    excludePrivate: z.ZodOptional<z.ZodBoolean>;
+    excludePublic: z.ZodOptional<z.ZodBoolean>;
+    loadProcess: z.ZodOptional<z.ZodBoolean>;
+    log: z.ZodOptional<z.ZodBoolean>;
+    logger: z.ZodOptional<z.ZodUnknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    privateToken: z.ZodOptional<z.ZodString>;
+    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
+}, z.core.$strip>;
 
 /**
  * A minimal representation of an environment key/value mapping.
- * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
+ * 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
@@ -13,87 +43,86 @@ type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => s
 type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
 type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
 /**
- * Options passed programmatically to `getDotenv`.
+ * Canonical programmatic options type (schema-derived).
+ * This type is the single source of truth for programmatic options.
  */
-interface GetDotenvOptions {
-    /**
-     * default target environment (used if `env` is not provided)
-     */
-    defaultEnv?: string;
+type GetDotenvOptions = z.output<typeof getDotenvOptionsSchemaResolved> & {
     /**
-     * token indicating a dotenv file
+     * Compile-time overlay: narrowed logger for DX (schema stores unknown).
      */
-    dotenvToken: string;
-    /**
-     * path to JS/TS module default-exporting an object keyed to dynamic variable functions
-     */
-    dynamicPath?: string;
+    logger?: Logger;
     /**
-     * Programmatic dynamic variables map. When provided, this takes precedence
-     * over {@link GetDotenvOptions.dynamicPath}.
+     * Compile-time overlay: narrowed dynamic map for DX (schema stores unknown).
      */
     dynamic?: GetDotenvDynamic;
+};
+
+declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: z.ZodOptional<z.ZodString>;
+    dotenvToken: z.ZodOptional<z.ZodString>;
+    dynamicPath: z.ZodOptional<z.ZodString>;
+    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    env: z.ZodOptional<z.ZodString>;
+    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
+    excludeEnv: z.ZodOptional<z.ZodBoolean>;
+    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
+    excludePrivate: z.ZodOptional<z.ZodBoolean>;
+    excludePublic: z.ZodOptional<z.ZodBoolean>;
+    loadProcess: z.ZodOptional<z.ZodBoolean>;
+    log: z.ZodOptional<z.ZodBoolean>;
+    logger: z.ZodOptional<z.ZodUnknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    privateToken: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+    capture: z.ZodOptional<z.ZodBoolean>;
+    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    redact: z.ZodOptional<z.ZodBoolean>;
+    warnEntropy: z.ZodOptional<z.ZodBoolean>;
+    entropyThreshold: z.ZodOptional<z.ZodNumber>;
+    entropyMinLength: z.ZodOptional<z.ZodNumber>;
+    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    paths: z.ZodOptional<z.ZodString>;
+    pathsDelimiter: z.ZodOptional<z.ZodString>;
+    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    vars: z.ZodOptional<z.ZodString>;
+    varsAssignor: z.ZodOptional<z.ZodString>;
+    varsAssignorPattern: z.ZodOptional<z.ZodString>;
+    varsDelimiter: z.ZodOptional<z.ZodString>;
+    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+type Scripts$1 = ScriptsTable;
+/**
+ * Canonical CLI options type derived from the Zod schema output.
+ * Includes CLI-only flags (debug/strict/capture/trace/redaction/entropy),
+ * stringly paths/vars, and inherited programmatic fields (minus normalized
+ * shapes that are handled by resolution).
+ */
+type GetDotenvCliOptions = z.output<typeof getDotenvCliOptionsSchemaResolved> & {
     /**
-     * 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)
+     * Compile-only overlay for DX: logger narrowed from unknown.
      */
     logger?: Logger;
     /**
-     * if populated, writes consolidated dotenv file to this path (follows dotenvExpand rules)
-     */
-    outputPath?: string;
-    /**
-     * array of input directory paths
+     * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
      */
-    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;
-}
+    scripts?: Scripts$1;
+};
+
+type ResolvedHelpConfig = Partial<GetDotenvCliOptions> & {
+    plugins: Record<string, unknown>;
+};
+/** 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.
@@ -111,58 +140,82 @@ interface GetDotenvOptions {
  * 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>>;
-};
+interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+    ns(name: string): Command;
+    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
+    resolveAndLoad(customOptions?: Partial<TOptions>, opts?: {
+        runAfterResolve?: boolean;
+    }): Promise<GetDotenvCliCtx<TOptions>>;
+    setOptionGroup(opt: Option, group: string): void;
+    /**
+     * Create a dynamic option whose description is computed at help time
+     * from the resolved configuration.
+     */
+    createDynamicOption(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
+    createDynamicOption<TValue = unknown>(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option;
+}
 /** Public plugin contract used by the GetDotenv CLI host. */
-interface GetDotenvCliPlugin {
+interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions> {
     id?: string;
     /**
      * Setup phase: register commands and wiring on the provided CLI instance.
      * Runs parent → children (pre-order).
      */
-    setup: (cli: GetDotenvCliPublic) => void | Promise<void>;
+    setup: (cli: GetDotenvCliPublic<TOptions>) => 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>;
+    afterResolve?: (cli: GetDotenvCliPublic<TOptions>, ctx: GetDotenvCliCtx<TOptions>) => 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.
+     * Zod schema for this plugin's config slice (from config.plugins[id]).
+     * Enforced object-like (ZodObject) to simplify code paths and inference.
      */
-    configSchema?: ZodType;
+    configSchema?: ZodObject;
     /**
      * Compositional children. Installed after the parent per pre-order.
      */
-    children: GetDotenvCliPlugin[];
+    children: GetDotenvCliPlugin<TOptions>[];
     /**
      * Compose a child plugin. Returns the parent to enable chaining.
      */
-    use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
+    use: (child: GetDotenvCliPlugin<TOptions>) => GetDotenvCliPlugin<TOptions>;
 }
-
-/** * 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>;
+/**
+ * Compile-time helper type: the plugin object returned by definePlugin always
+ * includes the instance-bound helpers as required members. Keeping the public
+ * interface optional preserves compatibility for ad-hoc/test plugins, while
+ * return types from definePlugin provide stronger DX for shipped/typed plugins.
+ */
+type PluginWithInstanceHelpers<TOptions extends GetDotenvOptions = GetDotenvOptions, TConfig = unknown> = GetDotenvCliPlugin<TOptions> & {
+    readConfig<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions>): Readonly<TCfg>;
+    createPluginDynamicOption<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions>, flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }, pluginCfg: Readonly<TCfg>) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
 };
 
-declare const awsPlugin: () => GetDotenvCliPlugin;
+declare const awsPlugin: () => PluginWithInstanceHelpers<GetDotenvOptions, {
+    profile?: string | undefined;
+    region?: string | undefined;
+    defaultRegion?: string | undefined;
+    profileKey?: string | undefined;
+    profileFallbackKey?: string | undefined;
+    regionKey?: string | undefined;
+    strategy?: "cli-export" | "none" | undefined;
+    loginOnDemand?: boolean | undefined;
+}>;
 
 /**
  * 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 Scripts = ScriptsTable;
 
 type BatchPluginOptions = {
     scripts?: Scripts;
@@ -173,11 +226,21 @@ type BatchPluginOptions = {
 /**
  * Batch plugin for the GetDotenv CLI host.
  *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * 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;
+declare const batchPlugin: (opts?: BatchPluginOptions) => PluginWithInstanceHelpers<GetDotenvOptions, {
+    scripts?: Record<string, string | {
+        cmd: string;
+        shell?: string | boolean | undefined;
+    }> | undefined;
+    shell?: string | boolean | undefined;
+    rootPath?: string | undefined;
+    globs?: string | undefined;
+    pkgCwd?: boolean | undefined;
+}>;
 
 type CmdPluginOptions = {
     /**
@@ -198,13 +261,13 @@ type CmdPluginOptions = {
  * - 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 cmdPlugin: (options?: CmdPluginOptions) => PluginWithInstanceHelpers<GetDotenvOptions, {}>;
 
-declare const demoPlugin: () => GetDotenvCliPlugin;
+declare const demoPlugin: () => PluginWithInstanceHelpers<GetDotenvOptions, {}>;
 
 type InitPluginOptions = {
     logger?: Logger;
 };
-declare const initPlugin: (opts?: InitPluginOptions) => GetDotenvCliPlugin;
+declare const initPlugin: (opts?: InitPluginOptions) => PluginWithInstanceHelpers<GetDotenvOptions, {}>;
 
 export { awsPlugin, batchPlugin, cmdPlugin, demoPlugin, initPlugin };