@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/plugins-demo.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 = 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
-     */
-    paths?: string[];
-    /**
-     * filename token indicating private variables
-     */
-    privateToken?: string;
-    /**
-     * explicit variables to include
+     * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
      */
-    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;
+};
+
+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,48 +140,65 @@ 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 demoPlugin: () => GetDotenvCliPlugin;
+declare const demoPlugin: () => PluginWithInstanceHelpers<GetDotenvOptions, {}>;
 
 export { demoPlugin };

package/dist/plugins-demo.mjs

@@ -1,8 +1,20 @@
 import { execa, execaCommand } from 'execa';
+import { z } from 'zod';
+import 'fs-extra';
+import 'path';
+import 'package-directory';
+import 'url';
+import 'yaml';
+import 'nanoid';
+import 'dotenv';
+import 'crypto';
 
 // Minimal tokenizer for shell-off execution:
 // Splits by whitespace while preserving quoted segments (single or double quotes).
-const tokenize = (command) => {
+// Optionally preserve doubled quotes inside quoted segments:
+// - default: "" => " (Windows/PowerShell style literal-quote escape)
+// - preserveDoubledQuotes: true => "" stays "" (needed for Node -e payloads)
+const tokenize = (command, opts) => {
     const out = [];
     let cur = '';
     let quote = null;
@@ -10,12 +22,16 @@ const tokenize = (command) => {
         const c = command.charAt(i);
         if (quote) {
             if (c === quote) {
-                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
-                // "" -> " and '' -> '
+                // Support doubled quotes inside a quoted segment:
+                // default: "" -> " and '' -> ' (Windows/PowerShell style)
+                // preserve: keep as "" to allow empty string literals in Node -e payloads
                 const next = command.charAt(i + 1);
                 if (next === quote) {
-                    cur += quote;
-                    i += 1; // skip the second quote
+                    {
+                        // Collapse to a single literal quote
+                        cur += quote;
+                        i += 1; // skip the second quote
+                    }
                 }
                 else {
                     // end of quoted segment
@@ -70,6 +86,17 @@ const stripOuterQuotes = (s) => {
     }
     return out;
 };
+// Extract exitCode/stdout/stderr from execa result or error in a tolerant way.
+const pickResult = (r) => {
+    const exit = r.exitCode;
+    const stdoutVal = r.stdout;
+    const stderrVal = r.stderr;
+    return {
+        exitCode: typeof exit === 'number' ? exit : Number.NaN,
+        stdout: typeof stdoutVal === 'string' ? stdoutVal : '',
+        stderr: typeof stderrVal === 'string' ? stderrVal : '',
+    };
+};
 // Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
 // expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
 const sanitizeEnv = (env) => {
@@ -78,19 +105,19 @@ const sanitizeEnv = (env) => {
     const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
     return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 };
-const runCommand = async (command, shell, opts) => {
+async function runCommand(command, shell, opts) {
     if (shell === false) {
         let file;
         let args = [];
-        if (Array.isArray(command)) {
-            file = command[0];
-            args = command.slice(1).map(stripOuterQuotes);
-        }
-        else {
+        if (typeof command === 'string') {
             const tokens = tokenize(command);
             file = tokens[0];
             args = tokens.slice(1);
         }
+        else {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
         if (!file)
             return 0;
         dbg('exec (plain)', { file, args, stdio: opts.stdio });
@@ -103,16 +130,15 @@ const runCommand = async (command, shell, opts) => {
             plainOpts.env = envSan;
         if (opts.stdio !== undefined)
             plainOpts.stdio = opts.stdio;
-        const result = await execa(file, args, plainOpts);
-        if (opts.stdio === 'pipe' && result.stdout) {
-            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+        const ok = pickResult((await execa(file, args, plainOpts)));
+        if (opts.stdio === 'pipe' && ok.stdout) {
+            process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
         }
-        const exit = result?.exitCode;
-        dbg('exit (plain)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
+        dbg('exit (plain)', { exitCode: ok.exitCode });
+        return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
     }
     else {
-        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        const commandStr = typeof command === 'string' ? command : command.join(' ');
         dbg('exec (shell)', {
             shell: typeof shell === 'string' ? shell : 'custom',
             stdio: opts.stdio,
@@ -126,17 +152,148 @@ const runCommand = async (command, shell, opts) => {
             shellOpts.env = envSan;
         if (opts.stdio !== undefined)
             shellOpts.stdio = opts.stdio;
-        const result = await execaCommand(commandStr, shellOpts);
-        const out = result?.stdout;
-        if (opts.stdio === 'pipe' && out) {
-            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+        const ok = pickResult((await execaCommand(commandStr, shellOpts)));
+        if (opts.stdio === 'pipe' && ok.stdout) {
+            process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
+        }
+        dbg('exit (shell)', { exitCode: ok.exitCode });
+        return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
+    }
+}
+
+/** 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.
+ */
+const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
+/** Build a sanitized env for child processes from base + overlay. */
+const buildSpawnEnv = (base, overlay) => {
+    const raw = {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+    };
+    // Drop undefined first
+    const entries = Object.entries(dropUndefined(raw));
+    if (process.platform === 'win32') {
+        // Windows: keys are case-insensitive; collapse duplicates
+        const byLower = new Map();
+        for (const [k, v] of entries) {
+            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
         }
-        const exit = result?.exitCode;
-        dbg('exit (shell)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
+        const out = {};
+        for (const [, [k, v]] of byLower)
+            out[k] = v;
+        // HOME fallback from USERPROFILE (common expectation)
+        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
+            const up = out['USERPROFILE'];
+            if (typeof up === 'string' && up.length > 0)
+                out['HOME'] = up;
+        }
+        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
+        const tmp = out['TMP'] ?? out['TEMP'];
+        if (typeof tmp === 'string' && tmp.length > 0) {
+            out['TMP'] = tmp;
+            out['TEMP'] = tmp;
+        }
+        return out;
+    }
+    // POSIX: keep keys as-is
+    const out = Object.fromEntries(entries);
+    // Ensure TMPDIR exists when any temp key is present (best-effort)
+    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
+    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
+        out['TMPDIR'] = tmpdir;
     }
+    return out;
 };
 
+/**
+ * Zod schemas for configuration files discovered by the new loader.
+ *
+ * Notes:
+ * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
+ * - RESOLVED: normalized shapes (paths always string[]).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
+ */
+// String-only env value map
+const stringMap = z.record(z.string(), z.string());
+const envStringMap = z.record(z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+const getDotenvConfigSchemaRaw = z.object({
+    dotenvToken: z.string().optional(),
+    privateToken: z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: z.array(z.string()).optional(),
+    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * Canonical source of truth for options shape. Public types are derived
+ * from these schemas (see consumers via z.output\<\>).
+ */
+// Minimal process env representation: string values or undefined to indicate "unset".
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    logger: z.unknown().optional(),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+});
+
+/**
+ * Instance-bound plugin config store.
+ * Host stores the validated/interpolated slice per plugin instance.
+ * The store is intentionally private to this module; definePlugin()
+ * provides a typed accessor that reads from this store for the calling
+ * plugin instance.
+ */
+const PLUGIN_CONFIG_STORE = new WeakMap();
+const _getPluginConfigForInstance = (plugin) => PLUGIN_CONFIG_STORE.get(plugin);
+
 /** src/cliHost/definePlugin.ts
  * Plugin contracts for the GetDotenv CLI host.
  *
@@ -144,26 +301,59 @@ const runCommand = async (command, shell, opts) => {
  * 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.
- *
- * @example
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
- */
-const definePlugin = (spec) => {
+/* eslint-disable tsdoc/syntax */
+function definePlugin(spec) {
     const { children = [], ...rest } = spec;
-    const plugin = {
+    // Default to a strict empty-object schema so “no-config” plugins fail fast
+    // on unknown keys and provide a concrete {} at runtime.
+    const effectiveSchema = spec.configSchema ?? z.object({}).strict();
+    // Build base plugin first, then extend with instance-bound helpers.
+    const base = {
         ...rest,
+        // Always carry a schema (strict empty by default) to simplify host logic
+        // and improve inference/ergonomics for plugin authors.
+        configSchema: effectiveSchema,
         children: [...children],
         use(child) {
             this.children.push(child);
             return this;
         },
     };
-    return plugin;
-};
+    // Attach instance-bound helpers on the returned plugin object.
+    const extended = base;
+    extended.readConfig = function (_cli) {
+        // Config is stored per-plugin-instance by the host (WeakMap in computeContext).
+        const value = _getPluginConfigForInstance(extended);
+        if (value === undefined) {
+            // Guard: host has not resolved config yet (incorrect lifecycle usage).
+            throw new Error('Plugin config not available. Ensure resolveAndLoad() has been called before readConfig().');
+        }
+        return value;
+    };
+    // Plugin-bound dynamic option factory
+    extended.createPluginDynamicOption = function (cli, flags, desc, parser, defaultValue) {
+        return cli.createDynamicOption(flags, (cfg) => {
+            // Prefer the validated slice stored per instance; fallback to help-bag
+            // (by-id) so top-level `-h` can render effective defaults before resolve.
+            const fromStore = _getPluginConfigForInstance(extended);
+            const id = extended.id;
+            let fromBag;
+            if (!fromStore && id) {
+                const maybe = cfg.plugins[id];
+                if (maybe && typeof maybe === 'object') {
+                    fromBag = maybe;
+                }
+            }
+            // Always provide a concrete object to dynamic callbacks:
+            // - With a schema: computeContext stores the parsed object.
+            // - Without a schema: computeContext stores {}.
+            // - Help-time fallback: coalesce to {} when only a by-id bag exists.
+            const cfgVal = (fromStore ?? fromBag ?? {});
+            return desc(cfg, cfgVal);
+        }, parser, defaultValue);
+    };
+    return extended;
+}
 
 /**
  * Batch services (neutral): resolve command and shell settings.
@@ -244,10 +434,9 @@ const demoPlugin = () => definePlugin({
             // Build a minimal node -e payload via argv array (avoid quoting issues).
             const code = `console.log(process.env.${key} ?? "")`;
             const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
             // Inherit stdio for an interactive demo. Use --capture for CI.
             await runCommand(['node', '-e', code], false, {
-                env: { ...process.env, ...dotenv },
+                env: buildSpawnEnv(process.env, ctx?.dotenv),
                 stdio: 'inherit',
             });
         });
@@ -282,22 +471,24 @@ const demoPlugin = () => definePlugin({
             const shell = resolveShell(bag?.scripts, input, bag?.shell);
             // Compose child env (parent + ctx.dotenv). This mirrors cmd/batch behavior.
             const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
             await runCommand(resolved, shell, {
-                env: { ...process.env, ...dotenv },
+                env: buildSpawnEnv(process.env, ctx?.dotenv),
                 stdio: 'inherit',
             });
         });
     },
     /**
      * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
-     * For the demo we just log once to hint where such logic would live.
+     * For the demo we emit a single breadcrumb only when GETDOTENV_DEBUG is set,
+     * keeping default runs (tests/CI/smoke) quiet.
      */
     afterResolve(_cli, ctx) {
-        const keys = Object.keys(ctx.dotenv);
-        if (keys.length > 0) {
-            // Keep noise low; a single-line breadcrumb is sufficient for the demo.
-            console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+        if (process.env.GETDOTENV_DEBUG) {
+            const keys = Object.keys(ctx.dotenv);
+            if (keys.length > 0) {
+                // Keep noise low; a single-line breadcrumb is sufficient for the demo.
+                console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+            }
         }
     },
 });