@karmaniverous/get-dotenv 5.2.2 → 5.2.4

package/README.md

@@ -390,7 +390,7 @@ Diagnostics and CI capture:
 - [Cascade and precedence](./guides/cascade.md)
 - [Shell execution behavior and quoting](./guides/shell.md)
 - [Config files and overlays](./guides/config.md)
-- [Plugin-first host and plugins](./guides/plugins.md)
+- [Plugin-first host and plugins](./guides/plugins/index.md)
 
 The guides are also included in the [hosted API docs](https://docs.karmanivero.us/get-dotenv).
 

package/dist/cliHost.cjs

@@ -12,6 +12,13 @@ var dotenv = require('dotenv');
 var crypto = require('crypto');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *

package/dist/cliHost.d.cts

@@ -269,17 +269,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 +311,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 +342,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.mts

@@ -269,17 +269,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 +311,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 +342,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

@@ -269,17 +269,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 +311,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 +342,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.mjs

@@ -9,6 +9,13 @@ import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
 import { createHash } from 'crypto';
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *

package/dist/getdotenv.cli.mjs

@@ -2066,6 +2066,13 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *
@@ -3202,11 +3209,8 @@ const cmdPlugin = (options = {}) => definePlugin({
             const { logger: _omit, ...envBag } = merged;
             const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
                 Boolean(merged.capture);
-            // Prefer explicit env injection: pass the resolved dotenv map to the child.
-            // This avoids leaking prior secrets from the parent process.env when
-            // exclusions (e.g., --exclude-private) are in effect.
-            const host = cli;
-            const ctx = host.getCtx();
+            // Prefer explicit env injection using the resolved dotenv map.
+            const ctx = cli.getCtx();
             const dotenv = (ctx?.dotenv ?? {});
             // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
             const traceOpt = merged.trace;
@@ -3299,36 +3303,6 @@ const cmdPlugin = (options = {}) => definePlugin({
     },
 });
 
-/**
- * Demo plugin (educational).
- *
- * Purpose
- * - Showcase how to build a plugin for the GetDotenv CLI host.
- * - Demonstrate:
- *   - Accessing the resolved dotenv context (ctx).
- *   - Executing child processes with explicit env injection.
- *   - Resolving commands via scripts and honoring per-script shell overrides.
- *   - Thin adapters: business logic stays minimal; use shared helpers.
- *
- * Key host APIs used:
- * - definePlugin: declare a plugin with setup and optional afterResolve.
- * - cli.ns(name): create a namespaced subcommand under the root CLI.
- * - cli.getCtx(): access \{ optionsResolved, dotenv, plugins?, pluginConfigs? \}.
- *
- * Design notes
- * - We use the shared runCommand() helper so behavior matches the built-in
- *   cmd/batch plugins (env sanitization, plain vs shell execution, stdio).
- * - We inject ctx.dotenv into child env explicitly to avoid bleeding prior
- *   secrets from process.env when exclusions are set (e.g., --exclude-private).
- * - We resolve scripts and shell using shared helpers to honor overrides:
- *   resolveCommand(scripts, input) and resolveShell(scripts, input, shell).
- *
- * Usage (examples)
- *   getdotenv demo ctx
- *   getdotenv demo run --print APP_SETTING
- *   getdotenv demo script echo OK
- *   getdotenv --trace demo run --print ENV_SETTING
- */
 const demoPlugin = () => definePlugin({
     id: 'demo',
     setup(cli) {

package/dist/index.cjs

@@ -2075,6 +2075,13 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *
@@ -3211,11 +3218,8 @@ const cmdPlugin = (options = {}) => definePlugin({
             const { logger: _omit, ...envBag } = merged;
             const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
                 Boolean(merged.capture);
-            // Prefer explicit env injection: pass the resolved dotenv map to the child.
-            // This avoids leaking prior secrets from the parent process.env when
-            // exclusions (e.g., --exclude-private) are in effect.
-            const host = cli;
-            const ctx = host.getCtx();
+            // Prefer explicit env injection using the resolved dotenv map.
+            const ctx = cli.getCtx();
             const dotenv = (ctx?.dotenv ?? {});
             // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
             const traceOpt = merged.trace;
@@ -3308,36 +3312,6 @@ const cmdPlugin = (options = {}) => definePlugin({
     },
 });
 
-/**
- * Demo plugin (educational).
- *
- * Purpose
- * - Showcase how to build a plugin for the GetDotenv CLI host.
- * - Demonstrate:
- *   - Accessing the resolved dotenv context (ctx).
- *   - Executing child processes with explicit env injection.
- *   - Resolving commands via scripts and honoring per-script shell overrides.
- *   - Thin adapters: business logic stays minimal; use shared helpers.
- *
- * Key host APIs used:
- * - definePlugin: declare a plugin with setup and optional afterResolve.
- * - cli.ns(name): create a namespaced subcommand under the root CLI.
- * - cli.getCtx(): access \{ optionsResolved, dotenv, plugins?, pluginConfigs? \}.
- *
- * Design notes
- * - We use the shared runCommand() helper so behavior matches the built-in
- *   cmd/batch plugins (env sanitization, plain vs shell execution, stdio).
- * - We inject ctx.dotenv into child env explicitly to avoid bleeding prior
- *   secrets from process.env when exclusions are set (e.g., --exclude-private).
- * - We resolve scripts and shell using shared helpers to honor overrides:
- *   resolveCommand(scripts, input) and resolveShell(scripts, input, shell).
- *
- * Usage (examples)
- *   getdotenv demo ctx
- *   getdotenv demo run --print APP_SETTING
- *   getdotenv demo script echo OK
- *   getdotenv --trace demo run --print ENV_SETTING
- */
 const demoPlugin = () => definePlugin({
     id: 'demo',
     setup(cli) {
@@ -4138,6 +4112,7 @@ function createCli(opts = {}) {
     };
 }
 
+exports.buildSpawnEnv = buildSpawnEnv;
 exports.createCli = createCli;
 exports.defineDynamic = defineDynamic;
 exports.dotenvExpand = dotenvExpand;

package/dist/index.d.cts

@@ -70,6 +70,24 @@ declare module '../cliHost/GetDotenvCli' {
     }
 }
 
+/** src/cliCore/spawnEnv.ts
+ * Build a sanitized environment bag for child processes.
+ *
+ * Requirements addressed:
+ * - Provide a single helper (buildSpawnEnv) to normalize/dedupe child env.
+ * - Drop undefined values (exactOptional semantics).
+ * - On Windows, dedupe keys case-insensitively and prefer the last value,
+ *   preserving the latest key's casing. Ensure HOME fallback from USERPROFILE.
+ *   Normalize TMP/TEMP consistency when either is present.
+ * - On POSIX, keep keys as-is; when a temp dir key is present (TMPDIR/TMP/TEMP),
+ *   ensure TMPDIR exists for downstream consumers that expect it.
+ *
+ * Adapter responsibility: pure mapping; no business logic.
+ */
+type SpawnEnv = Readonly<Partial<Record<string, string>>>;
+/** Build a sanitized env for child processes from base + overlay. */
+declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => SpawnEnv;
+
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
     paths?: string | string[];
@@ -456,5 +474,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
 export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };

package/dist/index.d.mts

@@ -70,6 +70,24 @@ declare module '../cliHost/GetDotenvCli' {
     }
 }
 
+/** src/cliCore/spawnEnv.ts
+ * Build a sanitized environment bag for child processes.
+ *
+ * Requirements addressed:
+ * - Provide a single helper (buildSpawnEnv) to normalize/dedupe child env.
+ * - Drop undefined values (exactOptional semantics).
+ * - On Windows, dedupe keys case-insensitively and prefer the last value,
+ *   preserving the latest key's casing. Ensure HOME fallback from USERPROFILE.
+ *   Normalize TMP/TEMP consistency when either is present.
+ * - On POSIX, keep keys as-is; when a temp dir key is present (TMPDIR/TMP/TEMP),
+ *   ensure TMPDIR exists for downstream consumers that expect it.
+ *
+ * Adapter responsibility: pure mapping; no business logic.
+ */
+type SpawnEnv = Readonly<Partial<Record<string, string>>>;
+/** Build a sanitized env for child processes from base + overlay. */
+declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => SpawnEnv;
+
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
     paths?: string | string[];
@@ -456,5 +474,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
 export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };

package/dist/index.d.ts

@@ -70,6 +70,24 @@ declare module '../cliHost/GetDotenvCli' {
     }
 }
 
+/** src/cliCore/spawnEnv.ts
+ * Build a sanitized environment bag for child processes.
+ *
+ * Requirements addressed:
+ * - Provide a single helper (buildSpawnEnv) to normalize/dedupe child env.
+ * - Drop undefined values (exactOptional semantics).
+ * - On Windows, dedupe keys case-insensitively and prefer the last value,
+ *   preserving the latest key's casing. Ensure HOME fallback from USERPROFILE.
+ *   Normalize TMP/TEMP consistency when either is present.
+ * - On POSIX, keep keys as-is; when a temp dir key is present (TMPDIR/TMP/TEMP),
+ *   ensure TMPDIR exists for downstream consumers that expect it.
+ *
+ * Adapter responsibility: pure mapping; no business logic.
+ */
+type SpawnEnv = Readonly<Partial<Record<string, string>>>;
+/** Build a sanitized env for child processes from base + overlay. */
+declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => SpawnEnv;
+
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
     paths?: string | string[];
@@ -456,5 +474,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
 export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };

package/dist/index.mjs

@@ -2072,6 +2072,13 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *
@@ -3208,11 +3215,8 @@ const cmdPlugin = (options = {}) => definePlugin({
             const { logger: _omit, ...envBag } = merged;
             const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
                 Boolean(merged.capture);
-            // Prefer explicit env injection: pass the resolved dotenv map to the child.
-            // This avoids leaking prior secrets from the parent process.env when
-            // exclusions (e.g., --exclude-private) are in effect.
-            const host = cli;
-            const ctx = host.getCtx();
+            // Prefer explicit env injection using the resolved dotenv map.
+            const ctx = cli.getCtx();
             const dotenv = (ctx?.dotenv ?? {});
             // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
             const traceOpt = merged.trace;
@@ -3305,36 +3309,6 @@ const cmdPlugin = (options = {}) => definePlugin({
     },
 });
 
-/**
- * Demo plugin (educational).
- *
- * Purpose
- * - Showcase how to build a plugin for the GetDotenv CLI host.
- * - Demonstrate:
- *   - Accessing the resolved dotenv context (ctx).
- *   - Executing child processes with explicit env injection.
- *   - Resolving commands via scripts and honoring per-script shell overrides.
- *   - Thin adapters: business logic stays minimal; use shared helpers.
- *
- * Key host APIs used:
- * - definePlugin: declare a plugin with setup and optional afterResolve.
- * - cli.ns(name): create a namespaced subcommand under the root CLI.
- * - cli.getCtx(): access \{ optionsResolved, dotenv, plugins?, pluginConfigs? \}.
- *
- * Design notes
- * - We use the shared runCommand() helper so behavior matches the built-in
- *   cmd/batch plugins (env sanitization, plain vs shell execution, stdio).
- * - We inject ctx.dotenv into child env explicitly to avoid bleeding prior
- *   secrets from process.env when exclusions are set (e.g., --exclude-private).
- * - We resolve scripts and shell using shared helpers to honor overrides:
- *   resolveCommand(scripts, input) and resolveShell(scripts, input, shell).
- *
- * Usage (examples)
- *   getdotenv demo ctx
- *   getdotenv demo run --print APP_SETTING
- *   getdotenv demo script echo OK
- *   getdotenv --trace demo run --print ENV_SETTING
- */
 const demoPlugin = () => definePlugin({
     id: 'demo',
     setup(cli) {
@@ -4135,4 +4109,4 @@ function createCli(opts = {}) {
     };
 }
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };

package/dist/plugins-aws.cjs

@@ -236,6 +236,13 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *