@karmaniverous/get-dotenv 4.6.0-0 → 5.0.0-0

package/README.md

@@ -2,12 +2,10 @@
 
 ## Requirements
 
-- Node.js >= 22.19 (this repository pins 22.19.0 for CI/reproducibility)
+- 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.
@@ -46,14 +44,6 @@ 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!
 
-## Breaking Changes
-
-In version 4.0.0, in addition to a full TypeScript refactor, I replaced the use of the unsafe `Function` constructor for dynamic variable processing with a MUCH safer dynamic module import.
-
-Dynamic importing is intrinsically asynchronous, and so far I haven't been able to figure out how to cram that into the synchronous `getDotenvSync` function. There really aren't THAT many users of this library, so rather than have async & sync versions that do different things, I just eliminated the sync version entirely.
-
-If you have a use case for sync dotenv processing and DON'T need dynamic variables, let me know and I'll put the restricted version back in. If you have an idea of how to make dynamic imports synchronous, I'm all ears!
-
 ## Testing
 
 This project uses Vitest with the V8 coverage provider. Run:
@@ -68,13 +58,58 @@ npm run test
 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.
+
+Examples:
+
+```bash
+# JSON config + .local variant, and a CLI skeleton named "acme"
+npx getdotenv init . \
+  --config-format json \
+  --with-local \
+  --cli-name acme \
+  --force
+```
+
+```bash
+# TypeScript config with a dynamic example; CLI named "toolbox"
+npx getdotenv init ./apps/toolbox \
+  --config-format ts \
+  --cli-name 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).
+- 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
+  - `--force` to overwrite all; `--yes` to skip all
+
+Notes:
+
+- Templates are shipped with the package and copied verbatim.
+- The CLI skeleton replaces `__CLI_NAME__` tokens with your chosen name.
+
 ## 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.
 
@@ -94,7 +129,7 @@ export default {
   ONE_MORE_TIME: ({ DESTRUCTRED_VARIABLE, ANOTHER_DYNAMIC_VARIABLE }) =>
     DESTRUCTRED_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.)
 
@@ -157,7 +192,6 @@ You can also use `getdotenv` from the command line:
 # Options:
 #   -e, --env <string>                  target environment (dotenv-expanded)
 #   -v, --vars <string>                 extra variables expressed as delimited key-value pairs (dotenv-expanded): KEY1=VAL1 KEY2=VAL2
-#   -c, --command <string>              command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)
 #   -o, --output-path <string>          consolidated output file  (dotenv-expanded)
 #   -s, --shell [string]                command execution shell, no argument for default OS shell or provide shell string (default OS shell)
 #   -S, --shell-off                     command execution shell OFF
@@ -184,8 +218,7 @@ 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: "=")
@@ -250,13 +283,87 @@ 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.
+
+- Anti-pattern:
+
+  ```json
+  { "scripts": { "script": "getdotenv echo $APP_SETTING" } }
+  ```
+
+  Then `npm run script -- -e dev` applies `-e` to `echo`, not to `getdotenv`.
+
+- Recommended:
+  ```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.
+
+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`.
+
+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.
+  - POSIX example:
+    ```
+    getdotenv --cmd 'node -e "console.log(process.env.APP_SETTING ?? \"\")"'
+    ```
+  - PowerShell example (single quotes are literal in PowerShell):
+    ```
+    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:
+  ```
+  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.
+- 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.
+
+---
+
 ## Guides
 
-- Cascade and precedence:
-  - ./guides/cascade.md
-- Shell execution behavior and quoting:
-  - ./guides/shell.md
+- [Cascade and precedence](./guides/cascade.md)
+- [Shell execution behavior and quoting](./guides/shell.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.
 
-The guides are also included in the hosted API docs.
+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)!