@karmaniverous/get-dotenv 5.2.4 → 5.2.6

package/dist/cliHost.d.cts

@@ -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).
  */
@@ -190,6 +231,72 @@ interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
     varsDelimiterPattern?: string;
 }
 
+/** 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;
+}
+/**
+ * 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;
+
 /** * Per-invocation context shared with plugins and actions. */
 type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     optionsResolved: TOptions;
@@ -209,7 +316,7 @@ declare const HELP_HEADER_SYMBOL: unique symbol;
  *
  * NOTE: This host is additive and does not alter the legacy CLI.
  */
-declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+declare class GetDotenvCli$1<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
     #private;
     /** Registered top-level plugins (composition happens via .use()) */
     private _plugins;
@@ -269,72 +376,29 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     private _runAfterResolve;
 }
 
-/** 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.
+ * GetDotenvCli with root helpers as real class methods.
+ * - attachRootOptions: installs legacy/base root flags on the command.
+ * - passOptions: merges flags (parent \< current), computes dotenv context once,
+ *   runs validation, and persists merged options for nested flows.
  */
-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>;
+declare class GetDotenvCli extends GetDotenvCli$1 {
     /**
-     * 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.
+     * Attach legacy root flags to this CLI instance. Defaults come from
+     * baseRootOptionDefaults when none are provided.
      */
-    configSchema?: ZodType;
+    attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+        includeCommandOption?: boolean;
+    }): this;
     /**
-     * Compositional children. Installed after the parent per pre-order.
+     * Install preSubcommand/preAction hooks that:
+     * - Merge options (parent round-trip + current invocation) using resolveCliOptions.
+     * - Persist the merged bag on the current command and on the host (for ergonomics).
+     * - Compute the dotenv context once via resolveAndLoad(serviceOptions).
+     * - Validate the composed env against discovered config (warn or --strict fail).
      */
-    children: GetDotenvCliPlugin[];
-    /**
-     * Compose a child plugin. Returns the parent to enable chaining.
-     */
-    use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
+    passOptions(defaults?: Partial<RootOptionsShape>): this;
 }
-/**
- * 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;
-
 /**
  * Helper to retrieve the merged root options bag from any action handler
  * that only has access to thisCommand. Avoids structural casts.

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).
  */
@@ -190,6 +231,72 @@ interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
     varsDelimiterPattern?: string;
 }
 
+/** 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;
+}
+/**
+ * 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;
+
 /** * Per-invocation context shared with plugins and actions. */
 type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     optionsResolved: TOptions;
@@ -209,7 +316,7 @@ declare const HELP_HEADER_SYMBOL: unique symbol;
  *
  * NOTE: This host is additive and does not alter the legacy CLI.
  */
-declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+declare class GetDotenvCli$1<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
     #private;
     /** Registered top-level plugins (composition happens via .use()) */
     private _plugins;
@@ -269,72 +376,29 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     private _runAfterResolve;
 }
 
-/** 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.
+ * GetDotenvCli with root helpers as real class methods.
+ * - attachRootOptions: installs legacy/base root flags on the command.
+ * - passOptions: merges flags (parent \< current), computes dotenv context once,
+ *   runs validation, and persists merged options for nested flows.
  */
-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>;
+declare class GetDotenvCli extends GetDotenvCli$1 {
     /**
-     * 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.
+     * Attach legacy root flags to this CLI instance. Defaults come from
+     * baseRootOptionDefaults when none are provided.
      */
-    configSchema?: ZodType;
+    attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+        includeCommandOption?: boolean;
+    }): this;
     /**
-     * Compositional children. Installed after the parent per pre-order.
+     * Install preSubcommand/preAction hooks that:
+     * - Merge options (parent round-trip + current invocation) using resolveCliOptions.
+     * - Persist the merged bag on the current command and on the host (for ergonomics).
+     * - Compute the dotenv context once via resolveAndLoad(serviceOptions).
+     * - Validate the composed env against discovered config (warn or --strict fail).
      */
-    children: GetDotenvCliPlugin[];
-    /**
-     * Compose a child plugin. Returns the parent to enable chaining.
-     */
-    use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
+    passOptions(defaults?: Partial<RootOptionsShape>): this;
 }
-/**
- * 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;
-
 /**
  * Helper to retrieve the merged root options bag from any action handler
  * that only has access to thisCommand. Avoids structural casts.

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).
  */
@@ -190,6 +231,72 @@ interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
     varsDelimiterPattern?: string;
 }
 
+/** 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;
+}
+/**
+ * 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;
+
 /** * Per-invocation context shared with plugins and actions. */
 type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     optionsResolved: TOptions;
@@ -209,7 +316,7 @@ declare const HELP_HEADER_SYMBOL: unique symbol;
  *
  * NOTE: This host is additive and does not alter the legacy CLI.
  */
-declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+declare class GetDotenvCli$1<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
     #private;
     /** Registered top-level plugins (composition happens via .use()) */
     private _plugins;
@@ -269,72 +376,29 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     private _runAfterResolve;
 }
 
-/** 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.
+ * GetDotenvCli with root helpers as real class methods.
+ * - attachRootOptions: installs legacy/base root flags on the command.
+ * - passOptions: merges flags (parent \< current), computes dotenv context once,
+ *   runs validation, and persists merged options for nested flows.
  */
-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>;
+declare class GetDotenvCli extends GetDotenvCli$1 {
     /**
-     * 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.
+     * Attach legacy root flags to this CLI instance. Defaults come from
+     * baseRootOptionDefaults when none are provided.
      */
-    configSchema?: ZodType;
+    attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+        includeCommandOption?: boolean;
+    }): this;
     /**
-     * Compositional children. Installed after the parent per pre-order.
+     * Install preSubcommand/preAction hooks that:
+     * - Merge options (parent round-trip + current invocation) using resolveCliOptions.
+     * - Persist the merged bag on the current command and on the host (for ergonomics).
+     * - Compute the dotenv context once via resolveAndLoad(serviceOptions).
+     * - Validate the composed env against discovered config (warn or --strict fail).
      */
-    children: GetDotenvCliPlugin[];
-    /**
-     * Compose a child plugin. Returns the parent to enable chaining.
-     */
-    use: (child: GetDotenvCliPlugin) => GetDotenvCliPlugin;
+    passOptions(defaults?: Partial<RootOptionsShape>): this;
 }
-/**
- * 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;
-
 /**
  * Helper to retrieve the merged root options bag from any action handler
  * that only has access to thisCommand. Avoids structural casts.