@karmaniverous/get-dotenv 6.1.0 → 6.2.0

package/README.md

@@ -1,3 +1,5 @@
+![This is how.](./assets/contributions.png)
+
 > Load, expand, and compose environment variables from a deterministic dotenv cascade, then execute commands under that context. Use get‑dotenv as a library, a CLI, or a plugin‑first host to build dotenv‑aware tooling with cross‑platform shell control, CI‑friendly capture, and clear diagnostics.
 
 # get-dotenv
@@ -24,19 +26,19 @@ See full guides:
 - [Shipped plugins](./guides/shipped/index.md)
 - [Authoring plugins](./guides/authoring/index.md) (host, lifecycle, exec, diagnostics)
 
-## Use Cases
-
-- Execute deployment steps across many repositories from one command sequence. See [batch plugin guide](./guides/shipped/batch.md)
-- Run config‑driven, environment‑aware operations with simple CLI commands. See [config guide](./guides/config.md)
-- Compose a rich CLI from shipped and third‑party plugins and share it across projects. See [shipped plugins overview](./guides/shipped/index.md)
-- Drive complex AWS workflows in an authenticated, environment‑aware context. See [aws plugin guide](./guides/shipped/aws.md)
-- Scaffold a project config and a host‑based CLI skeleton in seconds. See [init plugin guide](./guides/shipped/init.md)
-- Batch lint/build/test across a monorepo with deterministic output. See [batch plugin guide](./guides/shipped/batch.md)
-- Run cross‑platform commands in CI with normalized shells and capture. See [shell guide](./guides/shell.md)
-- Programmatically compose env and run tools inside Node scripts. See [Getting started](./guides/getting-started.md)
-- Add observability without leaking secrets using trace, redaction, and entropy warnings. See [diagnostics guide](./guides/authoring/diagnostics.md)
-- Author new plugins with maximum DX and minimal boilerplate. See [authoring plugins guide](./guides/authoring/index.md)
-
+## Use Cases
+
+- Execute deployment steps across many repositories from one command sequence. See [batch plugin guide](./guides/shipped/batch.md)
+- Run config‑driven, environment‑aware operations with simple CLI commands. See [config guide](./guides/config.md)
+- Compose a rich CLI from shipped and third‑party plugins and share it across projects. See [shipped plugins overview](./guides/shipped/index.md)
+- Drive complex AWS workflows in an authenticated, environment‑aware context. See [aws plugin guide](./guides/shipped/aws.md)
+- Scaffold a project config and a host‑based CLI skeleton in seconds. See [init plugin guide](./guides/shipped/init.md)
+- Batch lint/build/test across a monorepo with deterministic output. See [batch plugin guide](./guides/shipped/batch.md)
+- Run cross‑platform commands in CI with normalized shells and capture. See [shell guide](./guides/shell.md)
+- Programmatically compose env and run tools inside Node scripts. See [Getting started](./guides/getting-started.md)
+- Add observability without leaking secrets using trace, redaction, and entropy warnings. See [diagnostics guide](./guides/authoring/diagnostics.md)
+- Author new plugins with maximum DX and minimal boilerplate. See [authoring plugins guide](./guides/authoring/index.md)
+
 ## Requirements
 
 - Node.js ≥ 20 (this repository pins 22.19.0 for CI/reproducibility)
@@ -70,7 +72,7 @@ Embed a CLI quickly (shipped plugins wired for you):
 #!/usr/bin/env node
 import { createCli } from '@karmaniverous/get-dotenv/cli';
 
-await createCli({ alias: 'toolbox' })();
+await createCli({ alias: 'toolbox' })();
 ```
 
 More first steps and tips at [Getting Started](./guides/getting-started.md)
@@ -151,3 +153,7 @@ See [CHANGELOG.md](./CHANGELOG.md)
 ## License
 
 BSD‑3‑Clause — see [LICENSE](./LICENSE)
+
+---
+
+Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).

package/dist/cli.d.ts

@@ -107,9 +107,21 @@ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<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>;
 }
 /**
@@ -135,6 +147,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>;
@@ -178,6 +198,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>;
@@ -232,7 +260,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).
      */
@@ -253,11 +281,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\>.
      */
@@ -320,13 +352,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>;
 }
 /**