@karmaniverous/get-dotenv 5.2.3 → 5.2.5

package/dist/cliHost.d.mts

@@ -1,6 +1,47 @@
 import { Command } from 'commander';
 import { ZodType } from 'zod';
 
+/**
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
+ */
+type RootOptionsShape = {
+    env?: string;
+    vars?: string;
+    command?: string;
+    outputPath?: string;
+    shell?: string | boolean;
+    loadProcess?: boolean;
+    excludeAll?: boolean;
+    excludeDynamic?: boolean;
+    excludeEnv?: boolean;
+    excludeGlobal?: boolean;
+    excludePrivate?: boolean;
+    excludePublic?: boolean;
+    log?: boolean;
+    debug?: boolean;
+    capture?: boolean;
+    strict?: boolean;
+    redact?: boolean;
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    defaultEnv?: string;
+    dotenvToken?: string;
+    dynamicPath?: string;
+    trace?: boolean | string[];
+    paths?: string;
+    pathsDelimiter?: string;
+    pathsDelimiterPattern?: string;
+    privateToken?: string;
+    varsDelimiter?: string;
+    varsDelimiterPattern?: string;
+    varsAssignor?: string;
+    varsAssignorPattern?: string;
+    scripts?: ScriptsTable;
+};
 /**
  * Scripts table shape (configurable shell type).
  */
@@ -9,6 +50,27 @@ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<s
     shell?: TShell;
 }>;
 
+/**
+ * Adapter-layer augmentation: add chainable helpers to GetDotenvCli without
+ * coupling the core host to cliCore. Importing this module has side effects:
+ * it extends the prototype and merges types for consumers.
+ */
+declare module '../cliHost/GetDotenvCli' {
+    interface GetDotenvCli {
+        /**
+         * Attach legacy root flags to this CLI instance. Defaults come from
+         * baseRootOptionDefaults when none are provided.     */
+        attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+            includeCommandOption?: boolean;
+        }): this;
+        /**
+         * Install a preSubcommand hook that merges CLI flags (including parent
+         * round-trip) and resolves the dotenv context before executing actions.
+         * Defaults come from baseRootOptionDefaults when none are provided.
+         */ passOptions(defaults?: Partial<RootOptionsShape>): this;
+    }
+}
+
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
@@ -269,17 +331,41 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     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>;
+/** 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: GetDotenvCli, ctx: GetDotenvCliCtx) => void | Promise<void>;
+    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.
@@ -287,7 +373,8 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     configSchema?: ZodType;
     /**
      * Compositional children. Installed after the parent per pre-order.
-     */ children: GetDotenvCliPlugin[];
+     */
+    children: GetDotenvCliPlugin[];
     /**
      * Compose a child plugin. Returns the parent to enable chaining.
      */
@@ -317,4 +404,4 @@ declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
 declare const readMergedOptions: (cmd: Command) => GetDotenvCliOptions | undefined;
 
 export { GetDotenvCli, definePlugin, readMergedOptions };
-export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, ScriptsTable };
+export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, ScriptsTable };

package/dist/cliHost.d.ts

@@ -1,6 +1,47 @@
 import { Command } from 'commander';
 import { ZodType } from 'zod';
 
+/**
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
+ */
+type RootOptionsShape = {
+    env?: string;
+    vars?: string;
+    command?: string;
+    outputPath?: string;
+    shell?: string | boolean;
+    loadProcess?: boolean;
+    excludeAll?: boolean;
+    excludeDynamic?: boolean;
+    excludeEnv?: boolean;
+    excludeGlobal?: boolean;
+    excludePrivate?: boolean;
+    excludePublic?: boolean;
+    log?: boolean;
+    debug?: boolean;
+    capture?: boolean;
+    strict?: boolean;
+    redact?: boolean;
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    defaultEnv?: string;
+    dotenvToken?: string;
+    dynamicPath?: string;
+    trace?: boolean | string[];
+    paths?: string;
+    pathsDelimiter?: string;
+    pathsDelimiterPattern?: string;
+    privateToken?: string;
+    varsDelimiter?: string;
+    varsDelimiterPattern?: string;
+    varsAssignor?: string;
+    varsAssignorPattern?: string;
+    scripts?: ScriptsTable;
+};
 /**
  * Scripts table shape (configurable shell type).
  */
@@ -9,6 +50,27 @@ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<s
     shell?: TShell;
 }>;
 
+/**
+ * Adapter-layer augmentation: add chainable helpers to GetDotenvCli without
+ * coupling the core host to cliCore. Importing this module has side effects:
+ * it extends the prototype and merges types for consumers.
+ */
+declare module '../cliHost/GetDotenvCli' {
+    interface GetDotenvCli {
+        /**
+         * Attach legacy root flags to this CLI instance. Defaults come from
+         * baseRootOptionDefaults when none are provided.     */
+        attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+            includeCommandOption?: boolean;
+        }): this;
+        /**
+         * Install a preSubcommand hook that merges CLI flags (including parent
+         * round-trip) and resolves the dotenv context before executing actions.
+         * Defaults come from baseRootOptionDefaults when none are provided.
+         */ passOptions(defaults?: Partial<RootOptionsShape>): this;
+    }
+}
+
 /**
  * A minimal representation of an environment key/value mapping.
  * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
@@ -269,17 +331,41 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     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>;
+/** 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: GetDotenvCli, ctx: GetDotenvCliCtx) => void | Promise<void>;
+    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.
@@ -287,7 +373,8 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     configSchema?: ZodType;
     /**
      * Compositional children. Installed after the parent per pre-order.
-     */ children: GetDotenvCliPlugin[];
+     */
+    children: GetDotenvCliPlugin[];
     /**
      * Compose a child plugin. Returns the parent to enable chaining.
      */
@@ -317,4 +404,4 @@ declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
 declare const readMergedOptions: (cmd: Command) => GetDotenvCliOptions | undefined;
 
 export { GetDotenvCli, definePlugin, readMergedOptions };
-export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, ScriptsTable };
+export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, ScriptsTable };