@karmaniverous/get-dotenv 6.1.1 → 6.2.1

package/dist/plugins.mjs

@@ -38,26 +38,58 @@ import { versions, env } from 'process';
  * 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$2.record(z$2.string(), z$2.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$2.object({
+    /** Default environment name when `env` is not provided. */
     defaultEnv: z$2.string().optional(),
+    /** Base dotenv filename token (default `.env`). */
     dotenvToken: z$2.string().optional(),
+    /** Path to a dynamic variables module (JS/TS) to load and apply. */
     dynamicPath: z$2.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$2.record(z$2.string(), z$2.unknown()).optional(),
+    /** Selected environment name for this invocation (for env-scoped files and overlays). */
     env: z$2.string().optional(),
+    /** When true, skip applying dynamic variables. */
     excludeDynamic: z$2.boolean().optional(),
+    /** When true, skip environment-scoped dotenv files. */
     excludeEnv: z$2.boolean().optional(),
+    /** When true, skip global dotenv files. */
     excludeGlobal: z$2.boolean().optional(),
+    /** When true, skip private dotenv files. */
     excludePrivate: z$2.boolean().optional(),
+    /** When true, skip public dotenv files. */
     excludePublic: z$2.boolean().optional(),
+    /** When true, merge the final composed environment into `process.env`. */
     loadProcess: z$2.boolean().optional(),
+    /** When true, log the final environment map via `logger`. */
     log: z$2.boolean().optional(),
+    /** Logger used when `log` is enabled (console-compatible). */
     logger: z$2.unknown().default(console),
+    /** Optional output dotenv file path to write after composition. */
     outputPath: z$2.string().optional(),
+    /** Dotenv search paths (ordered). */
     paths: z$2.array(z$2.string()).optional(),
+    /** Private token suffix for private dotenv files (default `local`). */
     privateToken: z$2.string().optional(),
+    /** Explicit variables to overlay onto the composed dotenv map. */
     vars: processEnvSchema.optional(),
 });
 /**
@@ -65,6 +97,14 @@ const getDotenvOptionsSchemaRaw = z$2.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;
 
 /**
@@ -74,27 +114,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$2.boolean().optional(),
+    /** Fail on validation errors (schema/requiredKeys). */
     strict: z$2.boolean().optional(),
+    /** Capture child process stdio (useful for CI/tests). */
     capture: z$2.boolean().optional(),
+    /** Emit child env diagnostics (boolean or selected keys). */
     trace: z$2.union([z$2.boolean(), z$2.array(z$2.string())]).optional(),
+    /** Enable presentation-time redaction in trace/log output. */
     redact: z$2.boolean().optional(),
+    /** Enable entropy warnings in trace/log output. */
     warnEntropy: z$2.boolean().optional(),
+    /** Entropy threshold (bits/char) for warnings. */
     entropyThreshold: z$2.number().optional(),
+    /** Minimum value length to consider for entropy warnings. */
     entropyMinLength: z$2.number().optional(),
+    /** Regex patterns (strings) to suppress entropy warnings by key. */
     entropyWhitelist: z$2.array(z$2.string()).optional(),
+    /** Additional key-match patterns (strings) for redaction. */
     redactPatterns: z$2.array(z$2.string()).optional(),
+    /** Dotenv search paths provided as a single delimited string. */
     paths: z$2.string().optional(),
+    /** Delimiter string used to split `paths`. */
     pathsDelimiter: z$2.string().optional(),
+    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
     pathsDelimiterPattern: z$2.string().optional(),
+    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
     scripts: z$2.record(z$2.string(), z$2.unknown()).optional(),
+    /** Shell selection (`false` for shell-off, string for explicit shell). */
     shell: z$2.union([z$2.boolean(), z$2.string()]).optional(),
+    /** Extra variables expressed as a single delimited string of assignments. */
     vars: z$2.string().optional(),
+    /** Assignment operator used when parsing `vars`. */
     varsAssignor: z$2.string().optional(),
+    /** Regex pattern used as the assignment operator for `vars` parsing. */
     varsAssignorPattern: z$2.string().optional(),
+    /** Delimiter string used to split `vars`. */
     varsDelimiter: z$2.string().optional(),
+    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
     varsDelimiterPattern: z$2.string().optional(),
 });
 
@@ -118,17 +186,34 @@ const envStringMap = z$2.record(z$2.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$2.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$2.record(z$2.string(), z$2.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
+    scripts: z$2.record(z$2.string(), z$2.unknown()).optional(),
+    /** Keys required to be present in the final composed environment. */
     requiredKeys: z$2.array(z$2.string()).optional(),
+    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
     schema: z$2.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$2.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$2.record(z$2.string(), z$2.unknown()).optional(),
 });
 /**
@@ -958,13 +1043,21 @@ function traceChildEnv(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',
@@ -978,12 +1071,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: '=',
@@ -1530,6 +1618,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' };
@@ -1544,6 +1640,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 = {};
@@ -2003,6 +2107,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.
@@ -3215,16 +3329,29 @@ function attachAwsPreSubcommandHook(cli, plugin) {
 }
 
 /**
- * Zod schema for AWS plugin configuration.
+ * AWS plugin configuration schema.
+ *
+ * @remarks
+ * This Zod schema is used by the host to validate the `plugins.aws` config slice.
+ *
+ * @public
  */
 const awsPluginConfigSchema = z$2.object({
+    /** Preferred AWS profile name (overrides dotenv-derived profile keys when set). */
     profile: z$2.string().optional(),
+    /** Preferred AWS region (overrides dotenv-derived region key when set). */
     region: z$2.string().optional(),
+    /** Fallback region when region cannot be resolved from config/dotenv/AWS CLI. */
     defaultRegion: z$2.string().optional(),
+    /** Dotenv/config key for local profile lookup (default `AWS_LOCAL_PROFILE`). */
     profileKey: z$2.string().default('AWS_LOCAL_PROFILE').optional(),
+    /** Dotenv/config fallback key for profile lookup (default `AWS_PROFILE`). */
     profileFallbackKey: z$2.string().default('AWS_PROFILE').optional(),
+    /** Dotenv/config key for region lookup (default `AWS_REGION`). */
     regionKey: z$2.string().default('AWS_REGION').optional(),
+    /** Credential acquisition strategy (`cli-export` to resolve via AWS CLI, or `none` to skip). */
     strategy: z$2.enum(['cli-export', 'none']).default('cli-export').optional(),
+    /** When true, attempt `aws sso login` on-demand when credential export fails for an SSO profile. */
     loginOnDemand: z$2.boolean().default(false).optional(),
 });
 
@@ -14176,7 +14303,9 @@ function attachBatchOptions(plugin, cli) {
 const ScriptSchema = z$2.union([
     z$2.string(),
     z$2.object({
+        /** Command string to execute. */
         cmd: z$2.string(),
+        /** Optional shell override for this script entry. */
         shell: z$2.union([z$2.string(), z$2.boolean()]).optional(),
     }),
 ]);
@@ -14184,10 +14313,15 @@ const ScriptSchema = z$2.union([
  * Zod schema for batch plugin configuration.
  */
 const batchPluginConfigSchema = z$2.object({
+    /** Optional scripts table scoped to the batch plugin. */
     scripts: z$2.record(z$2.string(), ScriptSchema).optional(),
+    /** Optional default shell for batch execution (overridden by per-script shell when present). */
     shell: z$2.union([z$2.string(), z$2.boolean()]).optional(),
+    /** Root path for discovery, relative to CWD (or package root when pkgCwd is true). */
     rootPath: z$2.string().optional(),
+    /** Space-delimited glob patterns used to discover directories. */
     globs: z$2.string().optional(),
+    /** When true, resolve the batch root from the nearest package directory. */
     pkgCwd: z$2.boolean().optional(),
 });
 
@@ -14483,6 +14617,7 @@ const attachCmdParentInvoker = (cli, options, plugin) => {
  */
 const cmdPluginConfigSchema = z$2
     .object({
+    /** When true, expand the alias value before execution (default behavior when omitted). */
     expand: z$2.boolean().optional(),
 })
     .strict();

package/package.json

@@ -192,8 +192,7 @@
       ]
     },
     "npm": {
-      "publish": false,
-      "skipChecks": true
+      "publish": false
     }
   },
   "repository": {
@@ -222,5 +221,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.1.1"
+  "version": "6.2.1"
 }