@romaintaillandier1978/dotenv-never-lies 0.3.0 → 1.1.0

package/README.md

@@ -1,96 +1,90 @@
 # dotenv-never-lies
 
-> Parce que les variables d’environnement **mentent tout le temps**.
+> Because environment variables lie all the time.
 
-**dotenv-never-lies** valide, type et documente tes variables d’environnement à partir d’un schéma TypeScript / Zod.  
-Il échoue **vite**, **fort**, et **avant la prod**.
+**dotenv-never-lies** validates, types, and documents your environment variables from a TypeScript / Zod schema.  
+It fails fast, loud, and before production.
 
----
-
-## Pourquoi ?
+## Why?
 
-Parce que tout ça arrive **tout le temps** :
+Because all of this happens all the time:
 
-- ❌ une variable d’env manquante → **crash au runtime**
-- ❌ une URL mal formée → **bug subtil en prod**
-- ❌ la CI n’a pas été mise à jour après une nouvelle variable → **déploiement rouge incompréhensible**
-- ❌ un `process.env.FOO!` optimiste → **mensonge à toi-même**
+- ❌ a missing env variable → runtime crash
+- ❌ a malformed URL → subtle production bug
+- ❌ CI was not updated after a new variable → confusing red deployment
+- ❌ an optimistic `process.env.FOO!` → lying to yourself
 
-Et parce que `.env` est :
+And because `.env` files are:
 
-- non typé
-- non documenté
-- partagé à la main
-- rarement à jour
+- untyped
+- undocumented
+- shared manually
+- rarely up to date
 
-👉 **dotenv-never-lies** transforme cette configuration fragile en **contrat explicite**.
+👉 **dotenv-never-lies** turns this fragile configuration into an explicit contract.
 
 ---
 
-## Ce que fait la lib
+## What the library does
 
-- ✅ valide les variables d’environnement au démarrage
-- ✅ fournit un typage TypeScript fiable
-- ✅ documente chaque variable
-- ✅ expose un CLI pour la CI et les humains
-- ✅ permet des transformations complexes (arrays, parsing, coercion…)
+- ✅ validates environment variables at startup
+- ✅ provides reliable TypeScript typings
+- ✅ documents each variable
+- ✅ exposes a CLI for CI and humans
+- ✅ enables complex transformations (arrays, parsing, coercion…)
 
 ---
 
-## Ce que dotenv-never-lies n’est pas
+## What dotenv-never-lies is not
 
-Ce package a un périmètre volontairement **limité**.
+This package has a deliberately limited scope.
 
-- ❌ **Ce n’est pas un outil frontend**  
-  Il n’est pas destiné à être utilisé dans un navigateur.  
-  Pas de bundler, pas de `import.meta.env`, pas de variables exposées au client.
+- ❌ **It is not a frontend tool**  
+  It is not meant to be used in a browser.  
+  No bundler, no `import.meta.env`, no variables exposed to the client.
 
-- ❌ **Ce n’est pas un gestionnaire de secrets**  
-  Il ne chiffre rien, ne stocke rien, ne remplace ni Vault, ni AWS Secrets Manager,
-  ni les variables sécurisées de ton provider CI/CD.
+- ❌ **It is not a secrets manager**  
+  It does not encrypt anything, does not store anything, and does not replace Vault, AWS Secrets Manager,  
+  nor your CI/CD provider’s secure variables.
 
-- ❌ **Ce n’est pas une solution cross-runtime**  
-  Support ciblé : **Node.js**.  
-  Deno, Bun, Cloudflare Workers, edge runtimes : hors scope (pour l’instant).
+- ❌ **It is not a cross-runtime solution**  
+  Targeted support: **Node.js**.  
+  Deno, Bun, Cloudflare Workers, edge runtimes: out of scope (for now).
 
-- ❌ **Ce n’est pas un framework de configuration global**  
-  Il ne gère ni les fichiers YAML/JSON, ni les profiles dynamiques,
-  ni les overrides magiques par environnement.
+- ❌ **It is not a global configuration framework**  
+  It does not manage YAML/JSON files, dynamic profiles,  
+  nor magical per-environment overrides.
 
-- ❌ **Ce n’est pas permissif**  
-  S’il manque une variable ou qu’une valeur est invalide, ça plante.  
-  C’est le but.
+- ❌ **It is not permissive**  
+  If a variable is missing or a value is invalid, it crashes.  
+  That’s the point.
 
-En résumé :  
-**dotenv-never-lies** est fait pour des **APIs Node.js** et des **services backend**  
-qui préfèrent **échouer proprement au démarrage** plutôt que **bugger silencieusement en prod**.
+In short:  
+**dotenv-never-lies** is for **Node.js APIs** and **backend services**  
+that prefer to **fail cleanly at startup** rather than **silently break in production**.
 
 ---
 
-## Dependency warnings
-
-⚠️ Important
-dotenv-never-lies expose des schémas Zod dans son API publique.
-Zod v4 est requis.
-Mélanger les versions cassera l’inférence de types (et oui, ça fait mal).
-
 ## Installation
 
 ```bash
-yarn add dotenv-never-lies
-# ou
-npm install dotenv-never-lies
+npm install @romaintaillandier1978/dotenv-never-lies
+# or
+yarn add @romaintaillandier1978/dotenv-never-lies
 ```
 
-## Expansion des variables (`dotenv-expand`)
+## Dependencies and compatibility
+
+**[`zod`](https://www.npmjs.com/package/zod)** — dotenv-never-lies exposes Zod schemas in its public API.
 
-**dotenv-never-lies** gère automatiquement l’expansion des variables d’environnement,
-via [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand).
+⚠️ Important: Zod **v4.2.1** minimum is required.  
+Using Zod v3 will cause typing or inference errors.
 
-Cela permet de définir des variables composées à partir d’autres variables,
-sans duplication ni copier-coller fragile.
+**[`dotenv`](https://www.npmjs.com/package/dotenv)** allows dotenv-never-lies to automatically handle parsing of env files.
 
-### Exemple
+**[`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand)** allows dotenv-never-lies to automatically handle environment variable expansion. This lets you define variables composed from other variables without duplication or fragile copy-paste.
+
+**Example**
 
 ```env
 FRONT_A=https://a.site.com
@@ -100,51 +94,55 @@ FRONT_C=https://c.site.com
 NODE_CORS_ORIGIN="${FRONT_A};${FRONT_B};${FRONT_C}"
 ```
 
-## Définir un schéma
+## DNL schema
+
+The DNL schema is your new source of truth.
+
+(`dnl reverse-env` will help you scaffold the first skeleton)
+
+### schema location
 
-env.dnl.ts
+Recommended: `env.dnl.ts`
+
+Supported in this order for all CLI commands:
+
+1. `--schema path/to/my-dnl.ts`
+2. declared in `package.json`:
+
+```json
+{
+    ...
+    "dotenv-never-lies": {
+        "schema": "path/to/my-dnl.ts"
+    }
+    ...
+}
+```
+
+3. one of `env.dnl.ts`, `env.dnl.js`, `dnl.config.ts`, `dnl.config.js`
+
+### define a schema
 
 ```typescript
 import { z } from "zod";
-import { define } from "dotenv-never-lies";
+import { define } from "@romaintaillandier1978/dotenv-never-lies";
 
 export default define({
     NODE_ENV: {
-        description: "Environnement d’exécution",
+        description: "Runtime environment",
         schema: z.enum(["test", "development", "staging", "production"]),
     },
 
     NODE_PORT: {
-        description: "Port de l’API",
-        schema: z.coerce.number(),
+        description: "API port",
+        schema: z.coerce.number().default(3000),
     },
 
-    FRONT_A: {
-        description: "Mon site A",
+    FRONT_URL: {
+        description: "My website",
         schema: z.url(),
     },
 
-    FRONT_B: {
-        description: "Mon site B",
-        schema: z.url(),
-    },
-
-    FRONT_C: {
-        description: "Mon site C",
-        schema: z.url(),
-    },
-
-    NODE_CORS_ORIGIN: {
-        description: "URLs frontend autorisées à appeler cette API",
-        schema: z.string().transform((v) =>
-            v
-                .split(";")
-                .map((s) => s.trim())
-                .filter(Boolean)
-                .map((url) => z.url().parse(url))
-        ),
-    },
-
     JWT_SECRET: {
         description: "JWT Secret",
         schema: z.string(),
@@ -153,153 +151,285 @@ export default define({
 });
 ```
 
-## Utilisation runtime
+## Secrets handling
+
+Reminder: dotenv-never-lies is not a secrets manager.
+
+### declaration in the DNL schema
+
+A variable is considered secret if and only if it is explicitly marked in the schema with `secret: true`.  
+(`secret: undefined` is equivalent to `secret: false`)  
+This rule is intentionally strict.
+
+```ts
+JWT_SECRET: {
+    description: "JWT signing key",
+    schema: z.string(),
+    secret: true,
+}
+```
+
+### Secrets and CLI commands
+
+assert: validates secrets like any other variable
+
+reverse-env: when generating the schema, with `--guess-secret` option, the command tries to automatically identify sensitive variables (e.g. SECRET, KEY, TOKEN, PASSWORD).  
+**This detection is heuristic and must always be reviewed and corrected manually.**
+
+export: adapts behavior depending on the target format (env, docker, CI, Kubernetes…). See the table below for details by format.
+
+### During export
+
+Variables marked `secret: true` in the schema are treated differently depending on the export format.
+
+| Format        | Secrets included by default | Maskable (`--hide-secret`) | Excludable (`--exclude-secret`) | Notes                      |
+| ------------- | --------------------------- | -------------------------- | ------------------------------- | -------------------------- |
+| env           | yes                         | yes                        | yes                             | classic .env               |
+| docker-env    | yes                         | yes                        | yes                             | For --env-file             |
+| docker-args   | yes                         | yes                        | yes                             | For docker run -e          |
+| json          | yes                         | yes                        | yes                             | Debug / tooling            |
+| ts            | yes                         | yes                        | yes                             | Typed export               |
+| js            | yes                         | yes                        | yes                             | Runtime export             |
+| github-env    | yes                         | yes                        | yes                             | visible in logs            |
+| github-secret | secrets only                | no                         | yes                             | Via gh secret set          |
+| gitlab-env    | yes                         | yes                        | yes                             | GitLab CI variables        |
+| k8s-configmap | yes                         | yes                        | yes                             | warning if secret unmasked |
+| k8s-secret    | secrets only                | yes                        | yes                             | Kubernetes Secret          |
+
+## Variable lifecycle
+
+dotenv-never-lies works with three distinct representations of environment variables:
+
+1. **Raw value**  
+   The original value coming from the source (`.env` file or `process.env`).  
+   Always a string (or undefined).
+
+2. **Runtime value (validated)**  
+   The value after validation — and possible transformation — by the Zod schema.  
+   This value may be strongly typed (number, boolean, array, object, etc.).
+
+3. **Exported value**  
+   The value written by `dnl export`.
+    - For env-like formats (`env`, `docker-*`, `github-*`, `k8s-*`), this is the **raw value**, after validation.
+    - For `js`, `ts` and `json`, the runtime value can be exported using `--serialize-typed`.
+
+This separation ensures that validation, runtime usage and configuration export remain explicit and predictable.
+
+## Runtime usage
 
 ```typescript
 import envDef from "./env.dnl";
 
 export const ENV = envDef.load();
 
-if(ENV.NODE_ENV === "test"){...}
-
+// if (process.env.NODE_ENV && process.env.NODE_ENV === "test") {
+if (ENV.NODE_ENV === "test") {
+    doAdditionalTest();
+}
 
+const server = http.createServer(app);
+//server.listen(process.env.NODE_PORT||3000, () => {
+server.listen(ENV.NODE_PORT, () => {
+    console.log(`Server started on ${ENV.NODE_PORT}`);
+});
 ```
 
-Résultat :
+Result:
 
-- ENV.NODE_ENV est un enum
-- ENV.NODE_PORT est un number
-- ENV.FRONT_A ENV.FRONT_B ENV.FRONT_C sont des URLs valides
-- ENV.NODE_CORS_ORIGIN est un string[] contenant des URLs valides
-- ENV.JWT_SECRET est une string
+- `ENV.NODE_ENV` is an enum
+- `ENV.NODE_PORT` is a number
+- `FRONT_URL` is a valid URL
+- `ENV.JWT_SECRET` is a string
 
-Si une variable est absente ou invalide → le process s’arrête immédiatement. \
-C’est volontaire.
+If a variable is missing or invalid → the process exits immediately.  
+This is intentional.
 
-## Éviter `process.env` dans le code applicatif
+## Avoid `process.env` in application code
 
-Une fois le schéma chargé, l’accès aux variables d’environnement
-doit se faire exclusivement via l’objet `ENV`.
+Once the schema is loaded, environment variables  
+must be accessed exclusively via the `ENV` object.
 
-Cela garantit :
+This guarantees:
 
-- un typage strict
-- des valeurs validées
-- un point d’entrée unique pour la configuration
+- strict typing
+- validated values
+- a single entry point for configuration
 
-Pour identifier les usages résiduels de `process.env` dans votre codebase, un simple outil de recherche suffit :
+To identify residual `process.env` usages in your codebase, a simple search tool is enough:
 
 ```bash
 grep -R "process\.env" src
 ```
 
-Le choix de corriger (ou non) ces usages dépend du contexte et reste volontairement laissé au développeur.
+Choosing to refactor (or not) those usages depends on context and is intentionally left to the developer.
 
 ## CLI
 
-Le CLI permet de valider, charger, générer et documenter les variables d’environnement à partir d’un schéma `dotenv-never-lies`.
+The CLI lets you validate, load, generate, export, and document environment variables from a `dotenv-never-lies` schema.
+
+It is designed to be used:
 
-Il est conçu pour être utilisé :
+- locally (by humans)
+- in CI (without surprises)
+- before the application starts (not after)
 
-- en local (par des humains)
-- en CI (sans surprise)
-- avant que l’application ne démarre (et pas après)
+### Exit codes
 
-### Valider un fichier `.env` (CI-friendly)
+`dotenv-never-lies` uses explicit exit codes, designed for CI:
 
-Valide les variables sans les injecter dans `process.env`.
+| Code | Meaning                       |
+| ---: | ----------------------------- |
+|    0 | Success                       |
+|    1 | Usage error or internal error |
+|    2 | DNL schema not found          |
+|    3 | Environment validation failed |
+|    4 | Error during export           |
+
+### assert: Validate a `.env` file (CI-friendly)
+
+Validates variables without injecting them into `process.env`.
 
 ```bash
-dnl check --schema env.dnl.ts
+dnl assert --source .env --schema env.dnl.ts
 ```
 
-→ échoue si :
+Without `--source`, `dnl assert` validates `process.env`.  
+This is the recommended mode when variables are injected by the runtime or CI.
 
-- une variable est manquante
-- une valeur est invalide
-- le schéma n’est pas respecté
+→ fails if:
 
-### Charger les variables dans le process
+- a variable is missing
+- a value is invalid
+- the schema is not respected
 
-Charge et valide les variables dans `process.env`.
+### generate: Generate a .env file from the schema
+
+Generates a documented `.env` from the schema.
 
 ```bash
-dnl load --schema env.dnl.ts
+dnl generate --schema env.dnl.ts --out .env
 ```
 
-Usage typique : scripts de démarrage, tooling local.
+Useful for:
 
-### Générer un fichier .env à partir du schéma
+- bootstrapping a project
+- sharing a template
+- avoiding obsolete `.env.example` files
 
-Génère un .env documenté à partir du schéma.
+### reverse-env: Generate a schema from an existing .env
+
+Creates an `env.dnl.ts` file from a `.env`.
 
 ```bash
-dnl generate --schema env.dnl.ts --out .env
+dnl reverse-env --source .env
 ```
 
-Utile pour :
+Useful for:
 
-- initialiser un projet
-- partager un template
-- éviter les .env.example obsolètes
+- migrating an existing project
+- documenting a legacy configuration afterwards
 
-### Générer un schéma depuis un .env existant
+### explain: Display variables documentation
 
-Crée un fichier env.dnl.ts à partir d’un .env.
+Displays the list of known variables and their description.
 
 ```bash
-dnl reverse-env --source .env
+dnl explain
+```
+
+Sample output:
+
+```bash
+NODE_ENV: Runtime environment
+NODE_PORT: API port
+FRONT_URL: My website
+JWT_SECRET: JWT Secret
 ```
 
-Utile pour :
+### export: Export variables to other formats
+
+The `export` command transforms variables validated by the schema  
+into formats directly consumable by other tools (Docker, CI, Kubernetes, scripts…).
 
-- migrer un projet existant
-- documenter a posteriori une configuration legacy
+The schema remains the source of truth.  
+Values are validated before export.
+
+```bash
+dnl export <format>
+```
 
-### Afficher la documentation des variables
+By default, values are read from `process.env`.  
+A `.env` file can be provided via `--source`.
 
-Affiche la liste des variables connues et leur description.
+Examples:  
+Export environment variables as JSON from a `.env` file
 
 ```bash
-dnl print
+dnl export json --source .env
 ```
 
-Exemple de sortie :
+Clean a `.env` file (remove comments and extraneous lines)
 
 ```bash
-FRONT_A: Mon site A
-FRONT_B: Mon site B
-FRONT_C: Mon site C
-NODE_CORS_ORIGIN: URLs frontend autorisées à appeler cette API
-JWT_SECRET: JWT Secret
+dnl export env --source .env --out .env.clean
+dnl export env --source .env --out .env --force
+```
+
+Export variables as `docker-args`
 
+```bash
+dnl export docker-args --source .env
 ```
 
-TODO : check CI in real life.
+Result:
 
-## Usages dans la vraie vie
+```bash
+-e "NODE_ENV=production" -e "NODE_PORT=3000"
+```
+
+Export for GitHub Actions (variables)
+
+```bash
+dnl export github-env
+```
+
+Result:
+
+```bash
+printf '%s\n' "NODE_ENV=production" >> $GITHUB_ENV
+printf '%s\n' "NODE_PORT=3000" >> $GITHUB_ENV
+```
+
+There are a few more formats and options (see CLI docs `dnl export --help`).
+
+## Real-life usage
+
+### GitIgnore
+
+dotenv-never-lies creates temporary files in your project directory.  
+Add `.dnl/` to your `.gitignore`.
 
 ### Git
 
-#### Git hooks recommandés
+#### Recommended Git hooks
 
-Il est fortement conseillé d’utiliser **dotenv-never-lies** via des hooks Git :
+Using **dotenv-never-lies** via Git hooks is strongly recommended:
 
-- **pre-commit** : empêche de committer si la configuration locale n’est pas conforme au schéma
-- **post-merge** : détecte immédiatement les changements de schéma impactant l’environnement local
+- **pre-commit**: prevents committing if the local configuration is not compliant with the schema
+- **post-merge**: immediately detects schema changes impacting the local environment
 
-L’objectif est simple :  
-**si la configuration locale n’est pas conforme au schéma, le code ne doit pas être committé.**
+The goal is simple:  
+**if the local configuration is not compliant with the schema, code must not be committed.**
 
-Le schéma est la source de vérité, pas les fichiers `.env`.
+The schema is the source of truth, not `.env` files.
 
-Ces hooks permettent d’éviter les erreurs classiques :
+These hooks help avoid classic mistakes:
 
-- variable manquante après un pull
-- format invalide détecté trop tard
-- “ça marche chez moi” dû à un `.env` obsolète
+- missing variable after a pull
+- invalid format detected too late
+- “works on my machine” due to an outdated `.env`
 
-#### Installation des hooks
+#### Hooks installation
 
 ```bash
 git config core.hooksPath .githooks
@@ -317,3 +447,150 @@ EOF
 
 chmod +x .githooks/pre-commit .githooks/post-merge
 ```
+
+### GitLab CI
+
+Environment variables validation step.
+
+```yaml
+# .gitlab-ci.yml
+check-env:
+    stage: test
+    image: node:20-alpine
+    script:
+        - corepack enable
+        - yarn install --frozen-lockfile
+        - yarn dnl assert --source $DOT_ENV_FILE
+```
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/check-env.yml
+name: Check environment
+
+on: [push, pull_request]
+
+jobs:
+    check-env:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+
+            - run: corepack enable
+            - run: yarn install --frozen-lockfile
+
+            # Example with a .env file provided by a secret
+            - run: yarn dnl assert --source .env
+```
+
+The `.env` file can be generated from a GitHub secret or mounted dynamically.
+
+```yaml
+- run: echo "$ENV_FILE_CONTENT" > .env
+  env:
+      ENV_FILE_CONTENT: ${{ secrets.ENV_FILE }}
+```
+
+### Which commands should I use?
+
+|                               Situation | Command to use                 |
+| --------------------------------------: | ------------------------------ |
+|                             New project | generate                       |
+|            Existing project with a .env | reverse-env                    |
+|            Validate configuration in CI | assert                         |
+| Validate config injected by the runtime | assert                         |
+|                      Document variables | explain                        |
+|                   Generate a clean .env | export env                     |
+|                  Prepare a Docker build | export docker-\*               |
+|                  Inject variables in CI | export github-env / gitlab-env |
+|         Kubernetes (ConfigMap / Secret) | export k8s-\*                  |
+
+Simple rule:
+
+> The schema is always the source of truth.  
+> Commands only validate, document, or transform.
+
+## FAQ / Design choices
+
+### Why so strict?
+
+Because configuration errors are bugs, not warnings.
+
+If a variable is missing or invalid:
+
+- the application must not start
+- the error must be immediate and explicit
+
+Tolerating an invalid config is just moving the bug to production.
+
+### Why Node.js only?
+
+Because the target runtime is clear:
+
+- APIs
+- workers
+- jobs
+- CI
+
+Edge runtimes (Deno, Bun, Cloudflare Workers…) have:
+
+- different environment models
+- different constraints
+- different expectations
+
+They are deliberately out of scope.
+
+### Why Zod?
+
+Because Zod provides:
+
+- reliable TypeScript typing
+- consistent runtime validation
+- expressive transformations
+
+The schema is both:
+
+- documentation
+- contract
+- validation
+- typing source
+
+No other tool covers these four points as cleanly today.
+
+### Why not use dotenv-safe / env-schema / others?
+
+These tools:
+
+- partially validate
+- provide little or weak typing
+- do not really document
+- do not offer a coherent CLI
+
+dotenv-never-lies assumes a stricter scope,  
+but provides a full chain:  
+schema → validation → typing → CI → export.
+
+### Why not manage secrets?
+
+Because it is not the right level.
+
+dotenv-never-lies:
+
+- identifies secrets
+- can exclude, mask, or export them
+
+But it:
+
+- encrypts nothing
+- stores nothing
+
+It integrates with existing tools; it does not compete with them.
+
+# Conclusion:
+
+> dotenv-never-lies does not aim to be flexible. It aims to be reliable, explicit, and predictable.