@karmaniverous/get-dotenv 5.0.0-1 → 5.0.0

package/README.md

@@ -1,14 +1,12 @@
-# get-dotenv
-
-## Requirements
-
-- Node.js >= 20 (this repository pins 22.19.0 for CI/reproducibility)
+> **_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._**
 
-## API Reference
-Generated API documentation is hosted at:
-- https://docs.karmanivero.us/get-dotenv
+# get-dotenv
 
-The site is built with TypeDoc from the source code in this repository.
+[![npm version](https://img.shields.io/npm/v/@karmaniverous/get-dotenv.svg)](https://www.npmjs.com/package/@karmaniverous/get-dotenv)
+![Node Current](https://img.shields.io/node/v/@karmaniverous/get-dotenv) <!-- TYPEDOC_EXCLUDE -->
+[![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/get-dotenv)
+[![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/get-dotenv/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE -->
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/get-dotenv/tree/main/LICENSE.md)
 
 Load environment variables with a cascade of environment-aware dotenv files. You can:
 
@@ -44,6 +42,18 @@ You can always use `getdotenv` directly on the command line, but its REAL power
 
 When you plug your own [`commander`](https://www.npmjs.com/package/commander) CLI commands into the `getdotenv` base, they will execute within all of the environmental context created above!
 
+## Requirements
+
+- Node.js >= 20 (this repository pins 22.19.0 for CI/reproducibility)
+
+## API Reference
+
+Generated API documentation is hosted at:
+
+- https://docs.karmanivero.us/get-dotenv
+
+The site is built with TypeDoc from the source code in this repository.
+
 ## Testing
 
 This project uses Vitest with the V8 coverage provider. Run:
@@ -60,8 +70,7 @@ npm install @karmaniverous/get-dotenv
 
 ## Scaffold
 
-You can scaffold config files and a host-based CLI skeleton using the built-in
-init command. Templates are shipped with the package and copied verbatim.
+You can scaffold config files and a host-based CLI skeleton using the built-in init command. Templates are shipped with the package and copied verbatim.
 
 Examples:
 
@@ -83,20 +92,13 @@ npx getdotenv init ./apps/toolbox \
 
 Collision flow (when a destination file exists):
 
-- Interactive prompt: [o]verwrite, [e]xample, [s]kip, or their “all” variants
-  [O]/[E]/[S].
-- Non-interactive detection:
-  - Treated as `--yes` (Skip All) unless `--force` is provided (Overwrite All).
-  - Considered non-interactive when stdin or stdout is not a TTY OR when a
-    CI-like environment variable is present (`CI`, `GITHUB_ACTIONS`,
-    `BUILDKITE`, `TEAMCITY_VERSION`, `TF_BUILD`).
-- Precedence:
-  - `--force` > `--yes` > auto-detect (non-interactive => Skip All).
+- Interactive prompt: [o]verwrite, [e]xample, [s]kip, or their “all” variants [O]/[E]/[S].
+- Non-interactive detection: Treated as `--yes` (Skip All) unless `--force` is provided (Overwrite All). Considered non-interactive when stdin or stdout is not a TTY OR when a CI-like environment variable is present (`CI`, `GITHUB_ACTIONS`, `BUILDKITE`, `TEAMCITY_VERSION`, `TF_BUILD`).
+- Precedence: `--force` > `--yes` > auto-detect (non-interactive => Skip All).
 - Options overview:
   - `--config-format <json|yaml|js|ts>`
   - `--with-local` to generate `.local` alongside public config (JSON/YAML)
-  - `--cli-name <string>` for token substitution (`__CLI_NAME__`) in the CLI
-    skeleton
+  - `--cli-name <string>` for token substitution (`__CLI_NAME__`) in the CLI skeleton
   - `--force` to overwrite all; `--yes` to skip all
 
 Notes:
@@ -106,14 +108,15 @@ Notes:
 
 ## Usage
 
-````js
+```js
 import { getDotenv } from '@karmaniverous/get-dotenv';
 
-const dotenv = await getDotenv(options);```
+const dotenv = await getDotenv(options);
+```
 
 Options can be passed programmatically or set in a `getdotenv.config.json` file in your project root directory. The same file also sets default options for the `getdotenv` CLI or any child CLI you spawn from it.
 
-See the [child CLI example repo](https://github.com/karmaniverous/get-dotenv-child#configuration) for an extensiive discussion of the various config options and how & where to set them.
+See the [child CLI example repo](https://github.com/karmaniverous/get-dotenv-child#configuration) for an extensive discussion of the various config options and how & where to set them.
 
 ## Dynamic Processing
 
@@ -126,10 +129,10 @@ export default {
   SOME_DYNAMIC_VARIABLE: (dotenv) => someLogic(dotenv),
   ANOTHER_DYNAMIC_VARIABLE: (dotenv) =>
     someOtherLogic(dotenv.SOME_DYNAMIC_VARIABLE),
-  ONE_MORE_TIME: ({ DESTRUCTRED_VARIABLE, ANOTHER_DYNAMIC_VARIABLE }) =>
-    DESTRUCTRED_VARIABLE + ANOTHER_DYNAMIC_VARIABLE,
+  ONE_MORE_TIME: ({ DESTRUCTURED_VARIABLE, ANOTHER_DYNAMIC_VARIABLE }) =>
+    DESTRUCTURED_VARIABLE + ANOTHER_DYNAMIC_VARIABLE,
 };
-````
+```
 
 If the value corresponding to a key is a function, it will be executed with the current state of `dotenv` as its single argument and the result applied back to the `dotenv` object. Otherwise, the value will just be applied back to `dotenv`. (Although if you're going to do that then you might as well just create a public global variable in the first place.)
 
@@ -146,9 +149,7 @@ export default {
 };
 ```
 
-If `esbuild` is not installed and a direct import fails, get-dotenv attempts a
-simple fallback for single-file `.ts` modules without imports; otherwise it will
-throw with clear guidance to install `esbuild`.
+If `esbuild` is not installed and a direct import fails, get-dotenv attempts a simple fallback for single-file `.ts` modules without imports; otherwise it will throw with clear guidance to install `esbuild`.
 
 Programmatic users can skip files entirely and pass dynamic variables directly:
 
@@ -175,8 +176,7 @@ Notes:
   - Install `esbuild` (`npm i -D esbuild`).
 
 - “Unable to load dynamic TypeScript file …”:
-  - Install `esbuild`. A simple transpile fallback exists only for trivial
-    single-file modules; any imports in `dynamic.ts` require `esbuild` bundling.
+  - Install `esbuild`. A simple transpile fallback exists only for trivial single-file modules; any imports in `dynamic.ts` require `esbuild` bundling.
 
 ## Command Line Interface
 
@@ -218,7 +218,8 @@ You can also use `getdotenv` from the command line:
 #   --dynamic-path <string>             dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)
 #   --paths <string>                    dotenv-expanded delimited list of paths to dotenv directory (default: "./")
 #   --paths-delimiter <string>          paths delimiter string (default: " ")
-#   --paths-delimiter-pattern <string>  paths delimiter regex pattern#   --private-token <string>            dotenv-expanded token indicating private variables (default: "local")
+#   --paths-delimiter-pattern <string>  paths delimiter regex pattern
+#   --private-token <string>            dotenv-expanded token indicating private variables (default: "local")
 #   --vars-delimiter <string>           vars delimiter string (default: " ")
 #   --vars-delimiter-pattern <string>   vars delimiter regex pattern
 #   --vars-assignor <string>            vars assignment operator string (default: "=")
@@ -277,7 +278,7 @@ Note that `batch` executes its commands in sequence, rather than in parallel!
 
 To understand why, imagine running `npm install` in a dozen repos from the same command line. The visual feedback would be impossible to follow, and if something broke you'd have a really hard time figuring out why.
 
-Instead, everything runs in sequence, and you get a clear record of exactly what heppened and where. Also worth noting that many complex processes are resource hogs: you would not _want_ to run a dozen Serverless deployments at once!
+Instead, everything runs in sequence, and you get a clear record of exactly what happened and where. Also worth noting that many complex processes are resource hogs: you would not _want_ to run a dozen Serverless deployments at once!
 
 Meanwhile, [this issue](https://github.com/karmaniverous/get-dotenv/issues/7) documents the parallel-processing option requirement. Feel free to submit a PR!
 
@@ -285,9 +286,7 @@ Meanwhile, [this issue](https://github.com/karmaniverous/get-dotenv/issues/7) do
 
 ### Authoring npm scripts and the `-c`/`--cmd` alias
 
-When you run commands via `npm run`, flags after `--` are forwarded to your script
-and may be applied to the inner shell command instead of `getdotenv` unless you
-structure your script carefully.
+When you run commands via `npm run`, flags after `--` are forwarded to your script and may be applied to the inner shell command instead of `getdotenv` unless you structure your script carefully.
 
 - Anti-pattern:
 
@@ -301,22 +300,17 @@ structure your script carefully.
   ```json
   { "scripts": { "script": "getdotenv -c 'echo $APP_SETTING'" } }
   ```
-  Now `npm run script -- -e dev` applies `-e` to `getdotenv`, which loads and expands
-  variables before executing the inner command.
+  Now `npm run script -- -e dev` applies `-e` to `getdotenv`, which loads and expands variables before executing the inner command.
 
 Notes:
 
 - `-c`/`--cmd` is an alias of the `cmd` subcommand; do not use both in a single invocation.
-- On POSIX shells, prefer single quotes to prevent the outer shell from expanding `$VAR`
-  before Node sees it. On PowerShell, single quotes are also literal.
-- Script-level shell overrides (`scripts[name].shell`) still take precedence over the global
-  `--shell`.
+- On POSIX shells, prefer single quotes to prevent the outer shell from expanding `$VAR` before Node sees it. On PowerShell, single quotes are also literal.
+- Script-level shell overrides (`scripts[name].shell`) still take precedence over the global `--shell`.
 
 Important:
 
-- When using the parent alias `--cmd` with a Node eval payload, quote the entire
-  payload as a single token so Commander does not treat `-e/--eval` as
-  getdotenv’s `-e, --env` flag.
+- When using the parent alias `--cmd` with a Node eval payload, quote the entire payload as a single token so Commander does not treat `-e/--eval` as getdotenv’s `-e, --env` flag.
   - POSIX example:
     ```
     getdotenv --cmd 'node -e "console.log(process.env.APP_SETTING ?? \"\")"'
@@ -325,23 +319,19 @@ Important:
     ```
     getdotenv --cmd 'node -e "console.log(process.env.APP_SETTING ?? \"\")"'
     ```
-- If you do not need to pass additional parent flags after the command, you can
-  prefer the subcommand form instead:
+- If you do not need to pass additional parent flags after the command, you can prefer the subcommand form instead:
   ```
   getdotenv --shell-off cmd node -e "console.log(process.env.APP_SETTING ?? '')"
   ```
 
 Diagnostics and CI capture:
 
-- To capture child stdout/stderr deterministically (e.g., in CI), either set
-  the environment variable `GETDOTENV_STDIO=pipe` or pass `--capture`. Outputs
-  are buffered and re-emitted after completion.
+- To capture child stdout/stderr deterministically (e.g., in CI), either set the environment variable `GETDOTENV_STDIO=pipe` or pass `--capture`. Outputs are buffered and re-emitted after completion.
 - For debugging environment composition, use:
   ```
   getdotenv --trace [keys...] cmd node -e "0"
   ```
-  When provided without keys, `--trace` emits a concise origin line for every
-  key (parent | dotenv | unset) to stderr before the child process launches.
+  When provided without keys, `--trace` emits a concise origin line for every key (parent | dotenv | unset) to stderr before the child process launches.
 
 ---
 
@@ -349,21 +339,17 @@ Diagnostics and CI capture:
 
 - [Cascade and precedence](./guides/cascade.md)
 - [Shell execution behavior and quoting](./guides/shell.md)
+- [Config files and overlays](./guides/config.md)
+- [Plugin-first host and plugins](./guides/plugins.md)
 
 The guides are also included in the [hosted API docs](https://docs.karmanivero.us/get-dotenv).
 
----
-
 ## Generated CLI
 
-This package still supports generating a standalone CLI for your projects.
-For most use cases we recommend the new plugin-first host because it resolves
-dotenv context once per invocation, supports composable plugins, and provides
-better subprocess control and diagnostics. If you prefer a thin, fixed
-command surface with defaults baked into config, the generated CLI can be a
-good fit.
+This package still supports generating a standalone CLI for your projects. For most use cases we recommend the new plugin-first host because it resolves dotenv context once per invocation, supports composable plugins, and provides better subprocess control and diagnostics. If you prefer a thin, fixed command surface with defaults baked into config, the generated CLI can be a good fit.
+
+See the [Generated CLI guide](https://docs.karmanivero.us/get-dotenv/guides/generated-cli) for details
 
-See the Generated CLI guide for details:
-https://docs.karmanivero.us/get-dotenv/guides/generated-cli
+---
 
 See more great templates & tools on [my GitHub Profile](https://github.com/karmaniverous)!

package/dist/index.cjs

@@ -498,7 +498,8 @@ const cmdCommand$1 = new commander.Command()
     .description('execute command, conflicts with --command option (default subcommand)')
     .enablePositionalOptions()
     .passThroughOptions()
-    .action(async (_options, thisCommand) => {
+    .argument('[command...]')
+    .action(async (commandParts, _options, thisCommand) => {
     if (!thisCommand.parent)
         throw new Error(`unable to resolve parent command`);
     if (!thisCommand.parent.parent)
@@ -511,7 +512,12 @@ const cmdCommand$1 = new commander.Command()
     const pkgCwd = !!raw.pkgCwd;
     const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
     // Execute command.
-    const command = thisCommand.args.join(' ');
+    const args = Array.isArray(commandParts) ? commandParts : [];
+    // When no positional tokens are provided (e.g., option form `-c/--command`),
+    // the preSubcommand hook handles execution. Avoid a duplicate call here.
+    if (args.length === 0)
+        return;
+    const command = args.map(String).join(' ');
     await execShellCommandBatch({
         command: resolveCommand(getDotenvCliOptions.scripts, command),
         getDotenvCliOptions,
@@ -578,8 +584,9 @@ const cmdCommand = new commander.Command()
     .configureHelp({ showGlobalOptions: true })
     .enablePositionalOptions()
     .passThroughOptions()
-    .action(async (_options, thisCommand) => {
-    const args = thisCommand.args;
+    .argument('[command...]')
+    .action(async (commandParts, _options, thisCommand) => {
+    const args = Array.isArray(commandParts) ? commandParts : [];
     if (args.length === 0)
         return;
     if (!thisCommand.parent)

package/dist/index.mjs

@@ -495,7 +495,8 @@ const cmdCommand$1 = new Command()
     .description('execute command, conflicts with --command option (default subcommand)')
     .enablePositionalOptions()
     .passThroughOptions()
-    .action(async (_options, thisCommand) => {
+    .argument('[command...]')
+    .action(async (commandParts, _options, thisCommand) => {
     if (!thisCommand.parent)
         throw new Error(`unable to resolve parent command`);
     if (!thisCommand.parent.parent)
@@ -508,7 +509,12 @@ const cmdCommand$1 = new Command()
     const pkgCwd = !!raw.pkgCwd;
     const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
     // Execute command.
-    const command = thisCommand.args.join(' ');
+    const args = Array.isArray(commandParts) ? commandParts : [];
+    // When no positional tokens are provided (e.g., option form `-c/--command`),
+    // the preSubcommand hook handles execution. Avoid a duplicate call here.
+    if (args.length === 0)
+        return;
+    const command = args.map(String).join(' ');
     await execShellCommandBatch({
         command: resolveCommand(getDotenvCliOptions.scripts, command),
         getDotenvCliOptions,
@@ -575,8 +581,9 @@ const cmdCommand = new Command()
     .configureHelp({ showGlobalOptions: true })
     .enablePositionalOptions()
     .passThroughOptions()
-    .action(async (_options, thisCommand) => {
-    const args = thisCommand.args;
+    .argument('[command...]')
+    .action(async (commandParts, _options, thisCommand) => {
+    const args = Array.isArray(commandParts) ? commandParts : [];
     if (args.length === 0)
         return;
     if (!thisCommand.parent)

package/package.json

@@ -224,5 +224,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "5.0.0-1"
+  "version": "5.0.0"
 }