@karmaniverous/get-dotenv 6.1.1 → 6.2.0

package/dist/cliHost.d.ts

@@ -113,9 +113,21 @@ declare const defineScripts: <TShell extends string | boolean>() => <T extends S
  * @public
  */
 interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    /**
+     * Fully resolved option bag used to compute this context.
+     */
     optionsResolved: TOptions;
+    /**
+     * Final composed dotenv environment for this invocation.
+     */
     dotenv: ProcessEnv;
+    /**
+     * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
+     */
     plugins?: Record<string, unknown>;
+    /**
+     * Per-plugin validated configuration slices keyed by realized mount path.
+     */
     pluginConfigs?: Record<string, unknown>;
 }
 /**
@@ -141,6 +153,14 @@ interface BrandOptions {
  * For the current step this mirrors the RAW schema; later stages may further
  * narrow types post-resolution in the host pipeline.
  */
+/**
+ * CLI options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
 declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
     defaultEnv: z.ZodOptional<z.ZodString>;
     dotenvToken: z.ZodOptional<z.ZodString>;
@@ -184,6 +204,14 @@ declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
  * For now, this mirrors the RAW schema; future stages may materialize defaults
  * and narrow shapes as resolution is wired into the host.
  */
+/**
+ * Programmatic options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
 declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
     defaultEnv: z.ZodOptional<z.ZodString>;
     dotenvToken: z.ZodOptional<z.ZodString>;
@@ -238,7 +266,7 @@ type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
  * Canonical programmatic options type (schema-derived).
  * This type is the single source of truth for programmatic options.
  */
-type GetDotenvOptions = z.output<typeof getDotenvOptionsSchemaResolved> & {
+type GetDotenvOptions = Omit<z.output<typeof getDotenvOptionsSchemaResolved>, 'logger' | 'dynamic'> & {
     /**
      * Compile-time overlay: narrowed logger for DX (schema stores unknown).
      */
@@ -259,11 +287,15 @@ type Scripts = ScriptsTable;
  * stringly paths/vars, and inherited programmatic fields (minus normalized
  * shapes that are handled by resolution).
  */
-type GetDotenvCliOptions = z.output<typeof getDotenvCliOptionsSchemaResolved> & {
+type GetDotenvCliOptions = Omit<z.output<typeof getDotenvCliOptionsSchemaResolved>, 'logger' | 'dynamic' | 'scripts'> & {
     /**
      * Compile-only overlay for DX: logger narrowed from unknown.
      */
     logger: Logger;
+    /**
+     * Compile-only overlay for DX: dynamic map narrowed from unknown.
+     */
+    dynamic?: GetDotenvDynamic;
     /**
      * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
      */
@@ -336,13 +368,37 @@ interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOption
     getCtx(): GetDotenvCliCtx<TOptions>;
     /** Check whether a context has been resolved (non-throwing). */
     hasCtx(): boolean;
+    /**
+     * Resolve options and compute the dotenv context for this invocation.
+     *
+     * @param customOptions - Partial options to overlay for this invocation.
+     * @param opts - Optional resolver behavior switches (for example, whether to run `afterResolve`).
+     * @returns A promise resolving to the computed invocation context.
+     */
     resolveAndLoad(customOptions?: Partial<TOptions>, opts?: ResolveAndLoadOptions): Promise<GetDotenvCliCtx<TOptions>>;
+    /**
+     * Tag an option with a help group identifier for grouped root help rendering.
+     *
+     * @param opt - The Commander option to tag.
+     * @param group - Group identifier (for example, `base`, `app`, or `plugin:<name>`).
+     * @returns Nothing.
+     */
     setOptionGroup(opt: Option, group: string): void;
     /**
      * Create a dynamic option whose description is computed at help time
      * from the resolved configuration.
      */
+    /**
+     * Create a dynamic option whose description is computed at help time from the resolved configuration.
+     *
+     * @param flags - Commander option flags usage string.
+     * @param desc - Description builder called during help rendering with the resolved help config.
+     * @param parser - Optional argument parser.
+     * @param defaultValue - Optional default value.
+     * @returns A Commander `Option` instance with a dynamic description.
+     */
     createDynamicOption<Usage extends string>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option<Usage>;
+    /** {@inheritDoc} */
     createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
 }
 /**
@@ -405,7 +461,27 @@ interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOption
  * return types from definePlugin provide stronger DX for shipped/typed plugins.
  */
 interface PluginWithInstanceHelpers<TOptions extends GetDotenvOptions = GetDotenvOptions, TConfig = unknown, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> extends GetDotenvCliPlugin<TOptions, TArgs, TOpts, TGlobal> {
+    /**
+     * Read the validated (and interpolated) configuration slice for this plugin instance.
+     *
+     * @param cli - The plugin mount (or any command under this mount) used to resolve the invocation context.
+     * @returns The plugin configuration slice, typed as `TCfg`.
+     * @throws Error when called before the host has resolved the invocation context.
+     */
     readConfig<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions, unknown[], OptionValues, OptionValues>): Readonly<TCfg>;
+    /**
+     * Create a Commander option whose help-time description receives the resolved root help config
+     * and this plugin instance’s validated configuration slice.
+     *
+     * @typeParam TCfg - The plugin configuration slice type.
+     * @typeParam Usage - The Commander usage string for the option flags.
+     * @param cli - The plugin mount used to associate the option with a realized mount path.
+     * @param flags - Commander option flags usage string.
+     * @param desc - Description builder receiving the resolved help config and the plugin config slice.
+     * @param parser - Optional argument parser.
+     * @param defaultValue - Optional default value.
+     * @returns A Commander `Option` instance with a dynamic description.
+     */
     createPluginDynamicOption<TCfg = TConfig, Usage extends string = string>(cli: GetDotenvCliPublic<TOptions, unknown[], OptionValues, OptionValues>, flags: Usage, desc: (cfg: ResolvedHelpConfig, pluginCfg: Readonly<TCfg>) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option<Usage>;
 }
 /**
@@ -417,6 +493,14 @@ type DefineSpec<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs exte
      * passes it into setup; return void | Promise<void>.
      */
     ns: string;
+    /**
+     * Plugin setup hook.
+     *
+     * Called by the host during installation to attach commands/options/hooks to the provided mount.
+     *
+     * @param cli - The command mount created by the host for this plugin instance.
+     * @returns Nothing (or a promise resolving to nothing) after setup completes.
+     */
     setup: (cli: GetDotenvCliPublic<TOptions, TArgs, TOpts, TGlobal>) => void | Promise<void>;
 };
 /**
@@ -441,6 +525,27 @@ declare function definePlugin<TOptions extends GetDotenvOptions>(spec: DefineSpe
  * Checks GETDOTENV_STDIO env var or the provided bag capture flag.
  */
 declare const shouldCapture: (bagCapture?: boolean) => boolean;
+/**
+ * Result object returned by {@link runCommandResult}.
+ *
+ * @public
+ */
+interface RunCommandResult {
+    /**
+     * Exit code of the child process.
+     *
+     * Conventionally, `0` indicates success.
+     */
+    exitCode: number;
+    /**
+     * Captured standard output (stdout) as UTF-8 text.
+     */
+    stdout: string;
+    /**
+     * Captured standard error (stderr) as UTF-8 text.
+     */
+    stderr: string;
+}
 /**
  * Options for runCommandResult (buffered execution).
  *
@@ -485,17 +590,33 @@ interface RunCommandOptions {
  * - Never re-emits stdout/stderr to parent; returns captured buffers.
  * - Supports optional timeout (ms).
  */
-declare function runCommandResult(command: readonly string[], shell: false, opts?: RunCommandResultOptions): Promise<{
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-}>;
-declare function runCommandResult(command: string | readonly string[], shell: string | boolean | URL, opts?: RunCommandResultOptions): Promise<{
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-}>;
+declare function runCommandResult(command: readonly string[], shell: false, opts?: RunCommandResultOptions): Promise<RunCommandResult>;
+/**
+ * Execute a command and capture stdout/stderr (buffered).
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/timeout).
+ * @returns A promise resolving to the captured result.
+ */
+declare function runCommandResult(command: string | readonly string[], shell: string | boolean | URL, opts?: RunCommandResultOptions): Promise<RunCommandResult>;
+/**
+ * Execute a command and return its exit code.
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/stdio).
+ * @returns A promise resolving to the process exit code.
+ */
 declare function runCommand(command: readonly string[], shell: false, opts: RunCommandOptions): Promise<number>;
+/**
+ * Execute a command and return its exit code.
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/stdio).
+ * @returns A promise resolving to the process exit code.
+ */
 declare function runCommand(command: string | readonly string[], shell: string | boolean | URL, opts: RunCommandOptions): Promise<number>;
 
 /** src/cliHost/GetDotenvCli.ts
@@ -639,6 +760,71 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions,
  */
 declare const getRootCommand: (cmd: CommandUnknownOpts) => CommandUnknownOpts;
 
+/**
+ * Options for {@link groupPlugins}.
+ *
+ * This helper creates a “namespace-only” parent plugin (a command that exists only
+ * to group child plugins under a shared prefix, like `tooling getdotenv init`).
+ *
+ * The returned plugin is composable: call `.use(childPlugin)` to mount children.
+ *
+ * @typeParam TOptions - The host option bag type.
+ *
+ * @public
+ */
+interface GroupPluginsOptions<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    /**
+     * Namespace for the grouping command (the command name used in the CLI).
+     */
+    ns: string;
+    /**
+     * Long-form description shown when rendering help for the group command.
+     */
+    description?: string;
+    /**
+     * Short summary shown in the parent command’s subcommand list.
+     */
+    summary?: string;
+    /**
+     * Help group heading for this command when listed in the parent’s help output.
+     */
+    helpGroup?: string;
+    /**
+     * Optional aliases for the group command (e.g., `['gd']`).
+     */
+    aliases?: string[];
+    /**
+     * Optional hook to customize the group command mount (e.g., attach a note or
+     * a small set of options). Avoid adding actions here; keep this a group.
+     */
+    configure?: (cli: GetDotenvCliPublic<TOptions>) => void | Promise<void>;
+}
+/**
+ * Create a namespace-only parent plugin (a group command) for composing plugins
+ * under a shared prefix.
+ *
+ * This is a convenience wrapper around {@link definePlugin} that performs no
+ * action by default and exists only for command organization.
+ *
+ * @example
+ * ```ts
+ * program.use(
+ *   groupPlugins({
+ *     ns: 'getdotenv',
+ *     description: 'getdotenv utility functions',
+ *     aliases: ['gd'],
+ *   }).use(initPlugin()),
+ * );
+ * ```
+ *
+ * @typeParam TOptions - The host option bag type.
+ * @param options - Group plugin options.
+ * @returns A plugin instance that can `.use(...)` child plugins.
+ *
+ * @public
+ */
+declare function groupPlugins<TOptions extends GetDotenvOptions = GetDotenvOptions>(options: GroupPluginsOptions<TOptions>): PluginWithInstanceHelpers<TOptions, {}>;
+
 /** src/cliHost/invoke.ts
  * Shared helpers for composing child env overlays and preserving argv for Node -e.
  */
@@ -720,6 +906,21 @@ declare const resolveCommand: (scripts: ScriptsTable | undefined, command: strin
  */
 declare const resolveShell: <TShell extends string | boolean>(scripts: ScriptsTable<TShell> | undefined, command: string, shell: TShell | undefined) => TShell | false;
 
+/**
+ * Minimal shape accepted by {@link resolveCliOptions}.
+ *
+ * This exists to document the `scripts` property used for nesting and to avoid
+ * undocumented inline intersections in generated TypeDoc output.
+ *
+ * @public
+ */
+interface ResolveCliOptionsShape extends Partial<RootOptionsShape> {
+    /**
+     * Optional scripts table, typically injected from configuration sources and/or
+     * inherited from a parent invocation via `process.env.getDotenvCliOptions`.
+     */
+    scripts?: ScriptsTable;
+}
 /**
  * Result of CLI option resolution.
  */
@@ -741,9 +942,7 @@ interface ResolveCliOptionsResult<T> {
  * into a GetDotenvCliOptions-like object. Types are intentionally wide to
  * avoid cross-layer coupling; callers may cast as needed.
  */
-declare const resolveCliOptions: <T extends Partial<RootOptionsShape> & {
-    scripts?: ScriptsTable;
-}>(rawCliOptions: unknown, defaults: Partial<T>, parentJson?: string) => ResolveCliOptionsResult<T>;
+declare const resolveCliOptions: <T extends ResolveCliOptionsShape>(rawCliOptions: unknown, defaults: Partial<T>, parentJson?: string) => ResolveCliOptionsResult<T>;
 
 /**
  * Build a sanitized environment object for spawning child processes.
@@ -755,5 +954,5 @@ declare const resolveCliOptions: <T extends Partial<RootOptionsShape> & {
  */
 declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => NodeJS.ProcessEnv;
 
-export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
-export type { BrandOptions, DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, InferPluginConfig, PluginChildEntry, PluginFlattenedEntry, PluginNamespaceOverride, PluginWithInstanceHelpers, ResolveAndLoadOptions, ResolveCliOptionsResult, ResolvedHelpConfig, RootOptionsShape, RunCommandOptions, RunCommandResultOptions, ScriptDef, Scripts, ScriptsTable };
+export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, groupPlugins, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
+export type { BrandOptions, DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GroupPluginsOptions, InferPluginConfig, PluginChildEntry, PluginFlattenedEntry, PluginNamespaceOverride, PluginWithInstanceHelpers, ResolveAndLoadOptions, ResolveCliOptionsResult, ResolvedHelpConfig, RootOptionsShape, RunCommandOptions, RunCommandResultOptions, ScriptDef, Scripts, ScriptsTable };

package/dist/cliHost.mjs

@@ -21,26 +21,58 @@ import { Option, Command } from '@commander-js/extra-typings';
  * Minimal process env representation used by options and helpers.
  * Values may be `undefined` to indicate "unset".
  */
+/**
+ * Schema for an env-like record.
+ *
+ * Keys are environment variable names and values are either strings or `undefined`
+ * (to represent “unset”).
+ *
+ * @public
+ */
 const processEnvSchema = z.record(z.string(), z.string().optional());
 // RAW: all fields optional — undefined means "inherit" from lower layers.
+/**
+ * Programmatic options schema (raw).
+ *
+ * This schema is the canonical runtime source of truth for the `getDotenv()` programmatic API.
+ * All fields are optional; `undefined` generally means “inherit default/lower layer”.
+ *
+ * @public
+ */
 const getDotenvOptionsSchemaRaw = z.object({
+    /** Default environment name when `env` is not provided. */
     defaultEnv: z.string().optional(),
+    /** Base dotenv filename token (default `.env`). */
     dotenvToken: z.string().optional(),
+    /** Path to a dynamic variables module (JS/TS) to load and apply. */
     dynamicPath: z.string().optional(),
-    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    /** Dynamic map is intentionally wide for now; refine once sources are normalized. */
     dynamic: z.record(z.string(), z.unknown()).optional(),
+    /** Selected environment name for this invocation (for env-scoped files and overlays). */
     env: z.string().optional(),
+    /** When true, skip applying dynamic variables. */
     excludeDynamic: z.boolean().optional(),
+    /** When true, skip environment-scoped dotenv files. */
     excludeEnv: z.boolean().optional(),
+    /** When true, skip global dotenv files. */
     excludeGlobal: z.boolean().optional(),
+    /** When true, skip private dotenv files. */
     excludePrivate: z.boolean().optional(),
+    /** When true, skip public dotenv files. */
     excludePublic: z.boolean().optional(),
+    /** When true, merge the final composed environment into `process.env`. */
     loadProcess: z.boolean().optional(),
+    /** When true, log the final environment map via `logger`. */
     log: z.boolean().optional(),
+    /** Logger used when `log` is enabled (console-compatible). */
     logger: z.unknown().default(console),
+    /** Optional output dotenv file path to write after composition. */
     outputPath: z.string().optional(),
+    /** Dotenv search paths (ordered). */
     paths: z.array(z.string()).optional(),
+    /** Private token suffix for private dotenv files (default `local`). */
     privateToken: z.string().optional(),
+    /** Explicit variables to overlay onto the composed dotenv map. */
     vars: processEnvSchema.optional(),
 });
 /**
@@ -48,6 +80,14 @@ const getDotenvOptionsSchemaRaw = z.object({
  * For now, this mirrors the RAW schema; future stages may materialize defaults
  * and narrow shapes as resolution is wired into the host.
  */
+/**
+ * Programmatic options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
 const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
 
 /**
@@ -57,27 +97,55 @@ const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
  * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
  * CLI resolution pipeline.
  */
+/**
+ * CLI options schema (raw).
+ *
+ * Extends the programmatic options schema with CLI-only flags and stringly inputs
+ * which are normalized later by the host resolution pipeline.
+ *
+ * @public
+ */
 const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
     // CLI-specific fields (stringly inputs before preprocessing)
+    /** Enable verbose debug output (host-specific). */
     debug: z.boolean().optional(),
+    /** Fail on validation errors (schema/requiredKeys). */
     strict: z.boolean().optional(),
+    /** Capture child process stdio (useful for CI/tests). */
     capture: z.boolean().optional(),
+    /** Emit child env diagnostics (boolean or selected keys). */
     trace: z.union([z.boolean(), z.array(z.string())]).optional(),
+    /** Enable presentation-time redaction in trace/log output. */
     redact: z.boolean().optional(),
+    /** Enable entropy warnings in trace/log output. */
     warnEntropy: z.boolean().optional(),
+    /** Entropy threshold (bits/char) for warnings. */
     entropyThreshold: z.number().optional(),
+    /** Minimum value length to consider for entropy warnings. */
     entropyMinLength: z.number().optional(),
+    /** Regex patterns (strings) to suppress entropy warnings by key. */
     entropyWhitelist: z.array(z.string()).optional(),
+    /** Additional key-match patterns (strings) for redaction. */
     redactPatterns: z.array(z.string()).optional(),
+    /** Dotenv search paths provided as a single delimited string. */
     paths: z.string().optional(),
+    /** Delimiter string used to split `paths`. */
     pathsDelimiter: z.string().optional(),
+    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
     pathsDelimiterPattern: z.string().optional(),
+    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
     scripts: z.record(z.string(), z.unknown()).optional(),
+    /** Shell selection (`false` for shell-off, string for explicit shell). */
     shell: z.union([z.boolean(), z.string()]).optional(),
+    /** Extra variables expressed as a single delimited string of assignments. */
     vars: z.string().optional(),
+    /** Assignment operator used when parsing `vars`. */
     varsAssignor: z.string().optional(),
+    /** Regex pattern used as the assignment operator for `vars` parsing. */
     varsAssignorPattern: z.string().optional(),
+    /** Delimiter string used to split `vars`. */
     varsDelimiter: z.string().optional(),
+    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
     varsDelimiterPattern: z.string().optional(),
 });
 
@@ -101,17 +169,34 @@ const envStringMap = z.record(z.string(), stringMap);
  * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
  * Validates allowed top‑level keys without performing path normalization.
  */
+/**
+ * Config schema for discovered get-dotenv configuration documents (raw).
+ *
+ * This schema validates the allowed top-level keys for configuration files.
+ * It does not normalize paths or coerce types beyond Zod’s parsing.
+ *
+ * @public
+ */
 const getDotenvConfigSchemaRaw = z.object({
+    /** Root option defaults applied by the host (CLI-like, collapsed families). */
     rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
+    /** Help-time visibility map for root flags (false hides). */
     rootOptionVisibility: visibilityMap.optional(),
-    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
+    scripts: z.record(z.string(), z.unknown()).optional(),
+    /** Keys required to be present in the final composed environment. */
     requiredKeys: z.array(z.string()).optional(),
+    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
     schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    /** Public global variables (string-only). */
     vars: stringMap.optional(), // public, global
+    /** Public per-environment variables (string-only). */
     envVars: envStringMap.optional(), // public, per-env
     // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    /** Dynamic variable definitions (JS/TS only). */
     dynamic: z.unknown().optional(),
     // Per-plugin config bag; validated by plugins/host when used.
+    /** Per-plugin config slices keyed by realized mount path (for example, `aws/whoami`). */
     plugins: z.record(z.string(), z.unknown()).optional(),
 });
 /**
@@ -863,13 +948,21 @@ const redactObject = (obj, opts) => {
  * Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
  * Used as the bottom layer for CLI option resolution.
  */
+const baseScripts = {
+    'git-status': {
+        cmd: 'git branch --show-current && git status -s -u',
+        shell: true,
+    },
+};
 /**
- * Default values for root CLI options used by the host and helpers as the
- * baseline layer during option resolution.
+ * Default values for root CLI options used by the host and helpers as the baseline layer during option resolution.
  *
- * These defaults correspond to the "stringly" root surface (see `RootOptionsShape`)
- * and are merged by precedence with create-time overrides and any discovered
- * configuration `rootOptionDefaults` before CLI flags are applied.
+ * These defaults correspond to the “stringly” root surface (see `RootOptionsShape`) and are merged by precedence with:
+ * - create-time overrides
+ * - any discovered configuration `rootOptionDefaults`
+ * - and finally CLI flags at runtime
+ *
+ * @public
  */
 const baseRootOptionDefaults = {
     dotenvToken: '.env',
@@ -883,12 +976,7 @@ const baseRootOptionDefaults = {
     paths: './',
     pathsDelimiter: ' ',
     privateToken: 'local',
-    scripts: {
-        'git-status': {
-            cmd: 'git branch --show-current && git status -s -u',
-            shell: true,
-        },
-    },
+    scripts: baseScripts,
     shell: true,
     vars: '',
     varsAssignor: '=',
@@ -1435,6 +1523,14 @@ async function _execNormalized(command, shell, opts = {}) {
         return out;
     }
 }
+/**
+ * Execute a command and capture stdout/stderr (buffered).
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/timeout).
+ * @returns A promise resolving to the captured result.
+ */
 async function runCommandResult(command, shell, opts = {}) {
     // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
     const coreOpts = { stdio: 'pipe' };
@@ -1449,6 +1545,14 @@ async function runCommandResult(command, shell, opts = {}) {
     }
     return _execNormalized(command, shell, coreOpts);
 }
+/**
+ * Execute a command and return its exit code.
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/stdio).
+ * @returns A promise resolving to the process exit code.
+ */
 async function runCommand(command, shell, opts) {
     // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
     const callOpts = {};
@@ -1908,6 +2012,16 @@ function evaluateDynamicOptions(root, resolved) {
     visit(root);
 }
 
+/**
+ * Initialize a {@link GetDotenvCli} instance with help configuration and safe defaults.
+ *
+ * @remarks
+ * This is a low-level initializer used by the host constructor to keep `GetDotenvCli.ts`
+ * small and to centralize help/output behavior.
+ *
+ * @param cli - The CLI instance to initialize.
+ * @param headerGetter - Callback returning an optional help header string.
+ */
 function initializeInstance(cli, headerGetter) {
     // Configure grouped help: show only base options in default "Options";
     // subcommands show all of their own options.
@@ -2344,6 +2458,56 @@ const getRootCommand = (cmd) => {
     return node;
 };
 
+/**
+ * Create a namespace-only parent plugin (a group command) for composing plugins
+ * under a shared prefix.
+ *
+ * This is a convenience wrapper around {@link definePlugin} that performs no
+ * action by default and exists only for command organization.
+ *
+ * @example
+ * ```ts
+ * program.use(
+ *   groupPlugins({
+ *     ns: 'getdotenv',
+ *     description: 'getdotenv utility functions',
+ *     aliases: ['gd'],
+ *   }).use(initPlugin()),
+ * );
+ * ```
+ *
+ * @typeParam TOptions - The host option bag type.
+ * @param options - Group plugin options.
+ * @returns A plugin instance that can `.use(...)` child plugins.
+ *
+ * @public
+ */
+function groupPlugins(options) {
+    const ns = typeof options.ns === 'string' && options.ns.trim().length > 0
+        ? options.ns.trim()
+        : '';
+    if (!ns)
+        throw new Error('groupPlugins: options.ns must be a non-empty string.');
+    return definePlugin({
+        ns,
+        async setup(cli) {
+            if (typeof options.description === 'string')
+                cli.description(options.description);
+            if (typeof options.summary === 'string')
+                cli.summary(options.summary);
+            if (typeof options.helpGroup === 'string')
+                cli.helpGroup(options.helpGroup);
+            if (Array.isArray(options.aliases) && options.aliases.length > 0) {
+                cli.aliases(options.aliases);
+            }
+            if (typeof options.configure === 'function') {
+                await options.configure(cli);
+            }
+            return undefined;
+        },
+    });
+}
+
 /**
  * Build a help-time configuration bag for dynamic option descriptions.
  * Centralizes construction and reduces inline casts at call sites.
@@ -2648,4 +2812,4 @@ const buildSpawnEnv = (base, overlay) => {
  */
 const defineScripts = () => (t) => t;
 
-export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
+export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, groupPlugins, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };

package/dist/config.d.ts

@@ -120,6 +120,11 @@ type ProcessEnv = Record<string, string | undefined>;
  */
 type Scripts = ScriptsTable;
 
+/**
+ * Resolved configuration object type returned by {@link getDotenvConfigSchemaResolved}.
+ *
+ * @public
+ */
 type GetDotenvConfigResolved = {
     /**
      * Help-time/runtime root defaults applied by the host (collapsed families; CLI‑like).
@@ -195,6 +200,13 @@ declare const discoverConfigFiles: (importMetaUrl?: string) => Promise<ConfigFil
  * For JS/TS: default export is loaded; "dynamic" is allowed.
  */
 declare const loadConfigFile: (filePath: string) => Promise<GetDotenvConfigResolved>;
+/**
+ * Loaded configuration sources keyed by origin scope and privacy.
+ *
+ * This is the primary output of {@link resolveGetDotenvConfigSources}.
+ *
+ * @public
+ */
 interface ResolvedConfigSources {
     /** Configuration from the package root (public only). */
     packaged?: GetDotenvConfigResolved;