@karmaniverous/get-dotenv 6.0.0-1 → 6.1.0

package/dist/templates/cli/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { createCli } from '@karmaniverous/get-dotenv/cli';
+import {
+  awsPlugin,
+  awsWhoamiPlugin,
+  batchPlugin,
+  cmdPlugin,
+  initPlugin,
+} from '@karmaniverous/get-dotenv/plugins';
+
+import { helloPlugin } from './plugins/hello';
+
+await createCli({
+  alias: 'mycli',
+  compose: (program) =>
+    program
+      .use(
+        cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }),
+      )
+      .use(batchPlugin())
+      .use(awsPlugin().use(awsWhoamiPlugin()))
+      .use(initPlugin())
+      .use(helloPlugin()),
+})();

package/{templates/cli/ts → dist/templates/cli}/plugins/hello.ts

@@ -1,4 +1,7 @@
-import { definePlugin } from '@karmaniverous/get-dotenv/cliHost';
+import {
+  definePlugin,
+  getRootCommand,
+} from '@karmaniverous/get-dotenv/cliHost';
 import { z } from 'zod';
 
 const HelloConfigSchema = z.object({
@@ -8,28 +11,29 @@ const HelloConfigSchema = z.object({
 
 export const helloPlugin = () => {
   const plugin = definePlugin({
-    id: 'hello',
+    ns: 'hello',
     configSchema: HelloConfigSchema,
     setup(cli) {
       cli
-        .ns('hello')
         .description('Say hello with current dotenv context')
         .addOption(
           plugin.createPluginDynamicOption(
             cli,
             '--loud',
-            (_bag, cfg) =>
-              `print greeting in ALL CAPS${cfg.loud ? ' (default)' : ''}`,
+            (_bag, pluginCfg) =>
+              `print greeting in ALL CAPS${pluginCfg.loud ? ' (default)' : ''}`,
           ),
         )
         .action(() => {
           const ctx = cli.getCtx();
-          const name = '__CLI_NAME__';
+          // Derive CLI name from the true root command using a typed helper.
+          const rootName = getRootCommand(cli).name();
+
           const cfg = plugin.readConfig(cli);
-          const keys = Object.keys(ctx?.dotenv ?? {});
+          const keys = Object.keys(ctx.dotenv);
           const label = cfg.loud
-            ? `[${name}] DOTENV KEYS (${String(keys.length)}):`
-            : `[${name}] dotenv keys (${String(keys.length)}):`;
+            ? `[${rootName}] DOTENV KEYS (${String(keys.length)}):`
+            : `[${rootName}] dotenv keys (${String(keys.length)}):`;
           console.log(label, keys.join(', '));
         });
     },

package/dist/templates/config/js/getdotenv.config.js

@@ -0,0 +1,20 @@
+export default {
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
+  vars: { APP_SETTING: 'app_value' },
+  envVars: { dev: { ENV_SETTING: 'dev_value' } },
+  dynamic: {
+    GREETING: ({ APP_SETTING = '' }) => `Hello ${APP_SETTING}`,
+    // Example: env-aware dynamic value. The second argument receives the
+    // selected environment (if any); tailor behavior per environment.
+    // For example, with env='dev' this yields "for-dev"; when env is not
+    // provided, this returns an empty string.
+    ENV_TAG: (_vars, env) => (env ? `for-${env}` : ''),
+  },
+};

package/dist/templates/config/json/local/getdotenv.config.local.json

@@ -0,0 +1,7 @@
+{
+  "vars": { "APP_SECRET": "secret_value" },
+  "envVars": {
+    "dev": { "ENV_SECRET": "dev_secret" },
+    "test": { "ENV_SECRET": "test_secret" }
+  }
+}

package/dist/templates/config/json/public/getdotenv.config.json

@@ -0,0 +1,9 @@
+{
+  "vars": {
+    "APP_SETTING": "app_value"
+  },
+  "envVars": {
+    "dev": { "ENV_SETTING": "dev_value" },
+    "test": { "ENV_SETTING": "test_value" }
+  }
+}

package/dist/templates/config/public/getdotenv.config.json

@@ -0,0 +1,8 @@
+{
+  "vars": {
+    "APP_NAME": "my-app"
+  },
+  "envVars": {
+    "dev": { "DEV_ONLY": "1" }
+  }
+}

package/dist/templates/config/ts/getdotenv.config.ts

@@ -0,0 +1,28 @@
+import { defineGetDotenvConfig } from '@karmaniverous/get-dotenv';
+
+type Vars = {
+  APP_SETTING?: string;
+  ENV_SETTING?: string;
+};
+
+export default defineGetDotenvConfig<Vars>({
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
+  vars: { APP_SETTING: 'app_value' },
+  envVars: { dev: { ENV_SETTING: 'dev_value' } },
+  dynamic: {
+    GREETING: ({ APP_SETTING = '' }) => `${APP_SETTING}-ts`,
+    // Example: env-aware dynamic value. The second argument receives the
+    // selected environment (if any); tailor behavior per environment.
+    // For example, with env='dev' this yields "for-dev"; when env is not
+    // provided, this returns an empty string.
+    ENV_TAG: (_vars: Record<string, string | undefined>, env?: string) =>
+      env ? `for-${env}` : '',
+  },
+});

package/dist/templates/config/yaml/local/getdotenv.config.local.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SECRET: "secret_value"
+envVars:
+  dev:
+    ENV_SECRET: "dev_secret"
+  test:
+    ENV_SECRET: "test_secret"

package/dist/templates/config/yaml/public/getdotenv.config.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SETTING: "app_value"
+envVars:
+  dev:
+    ENV_SETTING: "dev_value"
+  test:
+    ENV_SETTING: "test_value"

package/dist/templates/getdotenv.config.js

@@ -0,0 +1,20 @@
+export default {
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
+  vars: { APP_SETTING: 'app_value' },
+  envVars: { dev: { ENV_SETTING: 'dev_value' } },
+  dynamic: {
+    GREETING: ({ APP_SETTING = '' }) => `Hello ${APP_SETTING}`,
+    // Example: env-aware dynamic value. The second argument receives the
+    // selected environment (if any); tailor behavior per environment.
+    // For example, with env='dev' this yields "for-dev"; when env is not
+    // provided, this returns an empty string.
+    ENV_TAG: (_vars, env) => (env ? `for-${env}` : ''),
+  },
+};

package/dist/templates/getdotenv.config.json

@@ -0,0 +1,9 @@
+{
+  "vars": {
+    "APP_SETTING": "app_value"
+  },
+  "envVars": {
+    "dev": { "ENV_SETTING": "dev_value" },
+    "test": { "ENV_SETTING": "test_value" }
+  }
+}

package/dist/templates/getdotenv.config.local.json

@@ -0,0 +1,7 @@
+{
+  "vars": { "APP_SECRET": "secret_value" },
+  "envVars": {
+    "dev": { "ENV_SECRET": "dev_secret" },
+    "test": { "ENV_SECRET": "test_secret" }
+  }
+}

package/dist/templates/getdotenv.config.local.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SECRET: "secret_value"
+envVars:
+  dev:
+    ENV_SECRET: "dev_secret"
+  test:
+    ENV_SECRET: "test_secret"

package/dist/templates/getdotenv.config.ts

@@ -0,0 +1,28 @@
+import { defineGetDotenvConfig } from '@karmaniverous/get-dotenv';
+
+type Vars = {
+  APP_SETTING?: string;
+  ENV_SETTING?: string;
+};
+
+export default defineGetDotenvConfig<Vars>({
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
+  vars: { APP_SETTING: 'app_value' },
+  envVars: { dev: { ENV_SETTING: 'dev_value' } },
+  dynamic: {
+    GREETING: ({ APP_SETTING = '' }) => `${APP_SETTING}-ts`,
+    // Example: env-aware dynamic value. The second argument receives the
+    // selected environment (if any); tailor behavior per environment.
+    // For example, with env='dev' this yields "for-dev"; when env is not
+    // provided, this returns an empty string.
+    ENV_TAG: (_vars: Record<string, string | undefined>, env?: string) =>
+      env ? `for-${env}` : '',
+  },
+});

package/dist/templates/getdotenv.config.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SETTING: "app_value"
+envVars:
+  dev:
+    ENV_SETTING: "dev_value"
+  test:
+    ENV_SETTING: "test_value"

package/dist/templates/hello.ts

@@ -0,0 +1,42 @@
+import {
+  definePlugin,
+  getRootCommand,
+} from '@karmaniverous/get-dotenv/cliHost';
+import { z } from 'zod';
+
+const HelloConfigSchema = z.object({
+  loud: z.boolean().optional().default(false),
+  color: z.string().optional(),
+});
+
+export const helloPlugin = () => {
+  const plugin = definePlugin({
+    ns: 'hello',
+    configSchema: HelloConfigSchema,
+    setup(cli) {
+      cli
+        .description('Say hello with current dotenv context')
+        .addOption(
+          plugin.createPluginDynamicOption(
+            cli,
+            '--loud',
+            (_bag, pluginCfg) =>
+              `print greeting in ALL CAPS${pluginCfg.loud ? ' (default)' : ''}`,
+          ),
+        )
+        .action(() => {
+          const ctx = cli.getCtx();
+          // Derive CLI name from the true root command using a typed helper.
+          const rootName = getRootCommand(cli).name();
+
+          const cfg = plugin.readConfig(cli);
+          const keys = Object.keys(ctx.dotenv);
+          const label = cfg.loud
+            ? `[${rootName}] DOTENV KEYS (${String(keys.length)}):`
+            : `[${rootName}] dotenv keys (${String(keys.length)}):`;
+          console.log(label, keys.join(', '));
+        });
+    },
+  });
+  return plugin;
+};

package/dist/templates/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { createCli } from '@karmaniverous/get-dotenv/cli';
+import {
+  awsPlugin,
+  awsWhoamiPlugin,
+  batchPlugin,
+  cmdPlugin,
+  initPlugin,
+} from '@karmaniverous/get-dotenv/plugins';
+
+import { helloPlugin } from './plugins/hello';
+
+await createCli({
+  alias: 'mycli',
+  compose: (program) =>
+    program
+      .use(
+        cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }),
+      )
+      .use(batchPlugin())
+      .use(awsPlugin().use(awsWhoamiPlugin()))
+      .use(initPlugin())
+      .use(helloPlugin()),
+})();

package/dist/templates/js/getdotenv.config.js

@@ -0,0 +1,20 @@
+export default {
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
+  vars: { APP_SETTING: 'app_value' },
+  envVars: { dev: { ENV_SETTING: 'dev_value' } },
+  dynamic: {
+    GREETING: ({ APP_SETTING = '' }) => `Hello ${APP_SETTING}`,
+    // Example: env-aware dynamic value. The second argument receives the
+    // selected environment (if any); tailor behavior per environment.
+    // For example, with env='dev' this yields "for-dev"; when env is not
+    // provided, this returns an empty string.
+    ENV_TAG: (_vars, env) => (env ? `for-${env}` : ''),
+  },
+};

package/dist/templates/json/local/getdotenv.config.local.json

@@ -0,0 +1,7 @@
+{
+  "vars": { "APP_SECRET": "secret_value" },
+  "envVars": {
+    "dev": { "ENV_SECRET": "dev_secret" },
+    "test": { "ENV_SECRET": "test_secret" }
+  }
+}

package/dist/templates/json/public/getdotenv.config.json

@@ -0,0 +1,9 @@
+{
+  "vars": {
+    "APP_SETTING": "app_value"
+  },
+  "envVars": {
+    "dev": { "ENV_SETTING": "dev_value" },
+    "test": { "ENV_SETTING": "test_value" }
+  }
+}

package/dist/templates/local/getdotenv.config.local.json

@@ -0,0 +1,7 @@
+{
+  "vars": { "APP_SECRET": "secret_value" },
+  "envVars": {
+    "dev": { "ENV_SECRET": "dev_secret" },
+    "test": { "ENV_SECRET": "test_secret" }
+  }
+}

package/dist/templates/local/getdotenv.config.local.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SECRET: "secret_value"
+envVars:
+  dev:
+    ENV_SECRET: "dev_secret"
+  test:
+    ENV_SECRET: "test_secret"

package/dist/templates/plugins/hello.ts

@@ -0,0 +1,42 @@
+import {
+  definePlugin,
+  getRootCommand,
+} from '@karmaniverous/get-dotenv/cliHost';
+import { z } from 'zod';
+
+const HelloConfigSchema = z.object({
+  loud: z.boolean().optional().default(false),
+  color: z.string().optional(),
+});
+
+export const helloPlugin = () => {
+  const plugin = definePlugin({
+    ns: 'hello',
+    configSchema: HelloConfigSchema,
+    setup(cli) {
+      cli
+        .description('Say hello with current dotenv context')
+        .addOption(
+          plugin.createPluginDynamicOption(
+            cli,
+            '--loud',
+            (_bag, pluginCfg) =>
+              `print greeting in ALL CAPS${pluginCfg.loud ? ' (default)' : ''}`,
+          ),
+        )
+        .action(() => {
+          const ctx = cli.getCtx();
+          // Derive CLI name from the true root command using a typed helper.
+          const rootName = getRootCommand(cli).name();
+
+          const cfg = plugin.readConfig(cli);
+          const keys = Object.keys(ctx.dotenv);
+          const label = cfg.loud
+            ? `[${rootName}] DOTENV KEYS (${String(keys.length)}):`
+            : `[${rootName}] dotenv keys (${String(keys.length)}):`;
+          console.log(label, keys.join(', '));
+        });
+    },
+  });
+  return plugin;
+};

package/dist/templates/public/getdotenv.config.json

@@ -0,0 +1,9 @@
+{
+  "vars": {
+    "APP_SETTING": "app_value"
+  },
+  "envVars": {
+    "dev": { "ENV_SETTING": "dev_value" },
+    "test": { "ENV_SETTING": "test_value" }
+  }
+}

package/dist/templates/public/getdotenv.config.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SETTING: "app_value"
+envVars:
+  dev:
+    ENV_SETTING: "dev_value"
+  test:
+    ENV_SETTING: "test_value"

package/dist/templates/ts/getdotenv.config.ts

@@ -0,0 +1,28 @@
+import { defineGetDotenvConfig } from '@karmaniverous/get-dotenv';
+
+type Vars = {
+  APP_SETTING?: string;
+  ENV_SETTING?: string;
+};
+
+export default defineGetDotenvConfig<Vars>({
+  // Help-time root defaults (example):
+  // rootOptionDefaults: {
+  //   redact: true,
+  //   // redactPatterns: ['API_KEY', 'SECRET'],
+  // },
+  // Help-time visibility (example): hide selected root flags in -h
+  // rootOptionVisibility: { capture: false },
+
+  vars: { APP_SETTING: 'app_value' },
+  envVars: { dev: { ENV_SETTING: 'dev_value' } },
+  dynamic: {
+    GREETING: ({ APP_SETTING = '' }) => `${APP_SETTING}-ts`,
+    // Example: env-aware dynamic value. The second argument receives the
+    // selected environment (if any); tailor behavior per environment.
+    // For example, with env='dev' this yields "for-dev"; when env is not
+    // provided, this returns an empty string.
+    ENV_TAG: (_vars: Record<string, string | undefined>, env?: string) =>
+      env ? `for-${env}` : '',
+  },
+});

package/dist/templates/yaml/local/getdotenv.config.local.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SECRET: "secret_value"
+envVars:
+  dev:
+    ENV_SECRET: "dev_secret"
+  test:
+    ENV_SECRET: "test_secret"

package/dist/templates/yaml/public/getdotenv.config.yaml

@@ -0,0 +1,7 @@
+vars:
+  APP_SETTING: "app_value"
+envVars:
+  dev:
+    ENV_SETTING: "dev_value"
+  test:
+    ENV_SETTING: "test_value"

package/getdotenv.config.json

@@ -1,19 +1 @@
-{
-  "//": "Packaged root defaults for get-dotenv (lowest precedence).",
-  "dotenvToken": ".env",
-  "privateToken": "local",
-  "paths": "./",
-  "loadProcess": true,
-  "shell": true,
-  "scripts": {
-    "git-status": {
-      "cmd": "git branch --show-current && git status -s -u",
-      "shell": true
-    }
-  },
-  "excludeDynamic": false,
-  "excludeEnv": false,
-  "excludeGlobal": false,
-  "excludePrivate": false,
-  "excludePublic": false
-}
+{}

package/package.json

@@ -13,58 +13,61 @@
     "url": "https://github.com/karmaniverous/get-dotenv/issues"
   },
   "dependencies": {
-    "commander": "^14.0.1",
+    "@commander-js/extra-typings": "^14.0.0",
+    "commander": "^14.0.2",
     "dotenv": "^17.2.3",
-    "execa": "^9.6.0",
+    "execa": "^9.6.1",
     "fs-extra": "^11.3.2",
-    "globby": "^15",
+    "globby": "^16",
     "nanoid": "^5.1.6",
     "package-directory": "^8.1.0",
-    "yaml": "^2.8.1",
-    "zod": "^4.1.12"
+    "yaml": "^2.8.2",
+    "zod": "^4.1.13"
   },
   "description": "Process dotenv files in an arbitrary location & optionally populate environment variables.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.51.0",
-    "@eslint/js": "^9.38.0",
-    "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-commonjs": "^28.0.8",
+    "@aws-sdk/client-sts": "^3.948.0",
+    "@dotenvx/dotenvx": "^1.51.2",
+    "@eslint/js": "^9.39.2",
+    "@rollup/plugin-alias": "^6.0.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-typescript": "^12.1.4",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^24",
-    "@vitest/coverage-v8": "^3.2.4",
-    "@vitest/eslint-plugin": "^1.3.23",
+    "@types/node": "^25",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/eslint-plugin": "^1.5.2",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "esbuild": "^0.25.11",
-    "eslint": "^9.38.0",
+    "esbuild": "^0.27.1",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsonc": "^2.21.0",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-tsdoc": "^0.4.0",
+    "eslint-plugin-tsdoc": "^0.5.0",
     "fs-extra": "^11.3.2",
-    "globals": "^16.4.0",
-    "jsonc-eslint-parser": "^2.4.1",
-    "knip": "^5.66.1",
-    "lefthook": "^2.0.0",
-    "npm-packlist": "^10.0.2",
-    "prettier": "^3.6.2",
-    "release-it": "^19.0.5",
-    "rimraf": "^6.0.1",
-    "rollup": "^4.52.5",
-    "rollup-plugin-dts": "^6.2.3",
+    "globals": "^16.5.0",
+    "jsonc-eslint-parser": "^2.4.2",
+    "knip": "^5.73.4",
+    "lefthook": "^2.0.11",
+    "npm-packlist": "^10.0.3",
+    "prettier": "^3.7.4",
+    "release-it": "^19.1.0",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.53.3",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-dts": "^6.3.0",
     "tslib": "^2.8.1",
-    "tsx": "^4.20.6",
-    "typedoc": "^0.28.14",
+    "tsx": "^4.21.0",
+    "typedoc": "^0.28.15",
     "typedoc-plugin-mdn-links": "^5.0.10",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.1",
+    "typescript-eslint": "^8.49.0",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.15"
   },
   "engines": {
     "node": ">=20"
@@ -76,6 +79,12 @@
         "default": "./dist/index.mjs"
       }
     },
+    "./cli": {
+      "import": {
+        "types": "./dist/cli.d.ts",
+        "default": "./dist/cli.mjs"
+      }
+    },
     "./cliHost": {
       "import": {
         "types": "./dist/cliHost.d.ts",
@@ -112,12 +121,6 @@
         "default": "./dist/plugins-cmd.mjs"
       }
     },
-    "./plugins/demo": {
-      "import": {
-        "types": "./dist/plugins-demo.d.ts",
-        "default": "./dist/plugins-demo.mjs"
-      }
-    },
     "./config": {
       "import": {
         "types": "./dist/config.d.ts",
@@ -189,7 +192,8 @@
       ]
     },
     "npm": {
-      "publish": true
+      "publish": false,
+      "skipChecks": true
     }
   },
   "repository": {
@@ -208,7 +212,6 @@
     "lint:fix": "eslint --fix . eslint.config.ts",
     "release": "dotenvx run -f .env.local -- release-it",
     "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
-    "stan:docs": "typedoc --emit none",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "verify:types": "node tools/verify-types.js",
@@ -219,5 +222,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.0.0-1"
+  "version": "6.1.0"
 }