@romaintaillandier1978/dotenv-never-lies 1.1.1 → 1.3.0

package/README.md

@@ -1,5 +1,8 @@
 # dotenv-never-lies
 
+> [!CAUTION]
+> Experimental — not yet ready to use.
+
 > Because environment variables lie all the time.
 
 **dotenv-never-lies** validates, types, and documents your environment variables from a TypeScript / Zod schema.  
@@ -28,10 +31,11 @@ And because `.env` files are:
 ## What the library does
 
 - ✅ validates environment variables at startup
+  powered by zod, enables complex transformations (arrays, parsing, coercion…)
+- ✅ provides infer .Env to get a first real life dnl schema
 - ✅ provides reliable TypeScript typings
 - ✅ documents each variable
-- ✅ exposes a CLI for CI and humans
-- ✅ enables complex transformations (arrays, parsing, coercion…)
+- ✅ exposes a CLI for CI and humans (dnl export)
 
 ---
 
@@ -98,7 +102,7 @@ NODE_CORS_ORIGIN="${FRONT_A};${FRONT_B};${FRONT_C}"
 
 The DNL schema is your new source of truth.
 
-(`dnl reverse-env` will help you scaffold the first skeleton)
+(`dnl infer` will help you scaffold the first skeleton)
 
 ### schema location
 
@@ -135,7 +139,7 @@ export default define({
 
     NODE_PORT: {
         description: "API port",
-        schema: z.coerce.number().default(3000),
+        schema: portSchema("NODE_PORT").default(3000),
     },
 
     FRONT_URL: {
@@ -169,32 +173,8 @@ JWT_SECRET: {
 }
 ```
 
-### 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          |
+More about secrets, and usage in cli commands :
+→ [Read secret documentation](docs/concepts/secrets.md)
 
 ## Variable lifecycle
 
@@ -302,12 +282,13 @@ This is the recommended mode when variables are injected by the runtime or CI.
 - a value is invalid
 - the schema is not respected
 
-### generate: Generate a .env file from the schema
+### init: Generate a .env file from the schema
 
-Generates a documented `.env` from the schema.
+Initialize a documented `.env` from the schema.
+Do not read any environment variables
 
 ```bash
-dnl generate --schema env.dnl.ts --out .env
+dnl init --schema env.dnl.ts --out .env
 ```
 
 Useful for:
@@ -316,18 +297,17 @@ Useful for:
 - sharing a template
 - avoiding obsolete `.env.example` files
 
-### reverse-env: Generate a schema from an existing .env
+### infer: discover a .envfile, and generate a schema from an existing .env
 
-Creates an `env.dnl.ts` file from a `.env`.
+Generate a DNL schema from an existing `.env` file.
 
 ```bash
-dnl reverse-env --source .env
+dnl infer --source .env
 ```
 
-Useful for:
+Useful for migrating an existing project
 
-- migrating an existing project
-- documenting a legacy configuration afterwards
+→ [Read infer documentation](docs/commands/infer.md)
 
 ### explain: Display variables documentation
 
@@ -402,6 +382,24 @@ printf '%s\n' "NODE_PORT=3000" >> $GITHUB_ENV
 
 There are a few more formats and options (see CLI docs `dnl export --help`).
 
+## export types : Exporting TypeScript types
+
+`dnl export types` generates a `.d.ts` file describing the **static contract** of your environment variables.
+
+This file is intentionally **conservative**.
+
+### Transformed variables
+
+If a variable uses a Zod `transform`, the exported type always reflects the **input type**, not the runtime output.
+
+In that case:
+
+- a warning is emitted in the CLI
+- the generated type is annotated with `@dnl-transform`
+- the runtime value returned by `assert()` may differ
+
+This is a deliberate design choice to avoid lying to TypeScript.
+
 ## Real-life usage
 
 ### GitIgnore
@@ -484,7 +482,7 @@ jobs:
             - run: corepack enable
             - run: yarn install --frozen-lockfile
 
-            # Example with a .env file provided by a secret
+            # Example with a .env file
             - run: yarn dnl assert --source .env
 ```
 
@@ -500,8 +498,8 @@ The `.env` file can be generated from a GitHub secret or mounted dynamically.
 
 |                               Situation | Command to use                 |
 | --------------------------------------: | ------------------------------ |
-|                             New project | generate                       |
-|            Existing project with a .env | reverse-env                    |
+|                             New project | init                           |
+|            Existing project with a .env | infer                          |
 |            Validate configuration in CI | assert                         |
 | Validate config injected by the runtime | assert                         |
 |                      Document variables | explain                        |
@@ -515,6 +513,69 @@ Simple rule:
 > The schema is always the source of truth.  
 > Commands only validate, document, or transform.
 
+### Tips
+
+**Alternative: minimal-intrusion integration**
+
+For a minimally invasive integration, you can add an optional Yarn script
+to validate your `.env` file before starting the application:
+
+```json
+{
+    "scripts": {
+        "env:check": "dnl assert --source .env",
+        "start:withdnl": "yarn env:check && yarn start"
+    }
+}
+```
+
+This validates the environment before startup, without changing runtime behavior or application code.
+
+> This is optional. It does not replace runtime validation.
+
+**Intellisens and JSdoc for env vars**
+
+After using `dnl export types` and importing the generated file, you get strong typing, auto-completion, IntelliSense and JSDoc for each environment variable.
+
+![IntelliSense and JSDoc for environment variables](docs/images/env-intellisense.png)
+
+> IntelliSense and JSDoc generated from the DNL schema after `dnl export types`.
+
+## Common issues / Troubleshooting
+
+### TypeScript projects with `rootDir: "src"`
+
+If your project uses a strict TypeScript setup with `rootDir: "src"`,
+and your `env.dnl.ts` file is located at the project root,
+TypeScript may report an error like:
+
+> File 'env.dnl.ts' is not under 'rootDir' (TS6059)
+
+**Option A** (preferred) :
+
+Keeps the schema outside application code, allowing reuse by the CLI, CI, and tooling.
+
+To fix this, include `env.dnl.ts` explicitly in your `tsconfig.json` and widen `rootDir`:
+
+```json
+{
+    "compilerOptions": {
+        "rootDir": "."
+    },
+    "include": ["src/**/*.ts", "env.dnl.ts"]
+}
+```
+
+This ensures `env.dnl.ts` is included in the TypeScript compilation graph.
+
+**Option B** :
+
+Move the schema into `./src` (for example `./src/env/env.dnl.ts`).
+
+This avoids TypeScript configuration changes, but makes the schema part of the application codebase
+
+You will need to specify schema location, see related section
+
 ## FAQ / Design choices
 
 ### Why so strict?

package/dist/cli/commands/assert.d.ts

@@ -1,7 +1,6 @@
-type AssertCliOptions = {
-    schema: string;
-    source: string;
+import { ProgramCliOptions } from "./program.js";
+export type AssertCliOptions = ProgramCliOptions & {
+    source?: string;
 };
 export declare const assertCommand: (opts?: AssertCliOptions | undefined) => Promise<void>;
-export {};
 //# sourceMappingURL=assert.d.ts.map

package/dist/cli/commands/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/assert.ts"],"names":[],"mappings":"AAOA,KAAK,gBAAgB,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,OAAO,gBAAgB,GAAG,SAAS,KAAG,OAAO,CAAC,IAAI,CAsBrF,CAAC"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/assert.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,OAAO,gBAAgB,GAAG,SAAS,KAAG,OAAO,CAAC,IAAI,CAsBrF,CAAC"}

package/dist/cli/commands/explain.d.ts

@@ -1,6 +1,6 @@
 import { Explanation } from "../utils/printer.js";
-type ExplainCliOptions = {
-    schema?: string | undefined;
+import { ProgramCliOptions } from "./program.js";
+export type ExplainCliOptions = ProgramCliOptions & {
     keys?: string[] | undefined;
     format?: "human" | "json" | undefined;
 };
@@ -9,5 +9,4 @@ export declare const explainCommand: (options?: ExplainCliOptions) => Promise<{
     result: Explanation[];
 }>;
 export declare const printHuman: (result: Explanation[]) => void;
-export {};
 //# sourceMappingURL=explain.d.ts.map

package/dist/cli/commands/explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAiB,MAAM,qBAAqB,CAAC;AAGjE,KAAK,iBAAiB,GAAG;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,UAAU,iBAAiB,KAAG,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,EAAE,CAAA;CAAE,CA2B7H,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,EAAE,SAqB/C,CAAC"}
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAiB,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG;IAChD,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,UAAU,iBAAiB,KAAG,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,EAAE,CAAA;CAAE,CA2B7H,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,EAAE,SAqB/C,CAAC"}

package/dist/cli/commands/export.d.ts

@@ -1,14 +1,14 @@
 import dnl from "../../index.js";
-export declare const exportFormatsNames: readonly ["docker-env", "docker-args", "env", "k8s-configmap", "k8s-secret", "github-env", "github-secret", "gitlab-env", "json", "ts", "js"];
+import { ProgramCliOptions } from "./program.js";
+export declare const exportFormatsNames: readonly ["docker-env", "docker-args", "env", "k8s-configmap", "k8s-secret", "github-env", "github-secret", "gitlab-env", "json", "ts", "js", "types"];
 export type ExportFormat = (typeof exportFormatsNames)[number];
 export type ExportResult = {
     content: string;
     warnings: string[];
     out?: string;
 };
-export type ExportCliOptions = {
+export type ExportCliOptions = ProgramCliOptions & {
     format: ExportFormat;
-    schema?: string | undefined;
     source?: string | undefined;
     hideSecret?: boolean;
     excludeSecret?: boolean;
@@ -32,4 +32,5 @@ export declare const exportGitlabEnv: (envDef: dnl.EnvDefinitionHelper<any>, opt
 export declare const exportJson: (envDef: dnl.EnvDefinitionHelper<any>, options: ExportCliOptions, warnings: string[]) => string;
 export declare const exportTs: (envDef: dnl.EnvDefinitionHelper<any>, options: ExportCliOptions, warnings: string[]) => string;
 export declare const exportJs: (envDef: dnl.EnvDefinitionHelper<any>, options: ExportCliOptions, warnings: string[]) => string;
+export declare const exportDts: (envDef: dnl.EnvDefinitionHelper<any>, options: ExportCliOptions, warnings: string[]) => string;
 //# sourceMappingURL=export.d.ts.map

package/dist/cli/commands/export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/export.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/export.ts"],"names":[],"mappings":"AAAA,OAAO,GAA4B,MAAM,gBAAgB,CAAC;AAM1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,eAAO,MAAM,kBAAkB,wJAarB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/D,MAAM,MAAM,YAAY,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IAC/C,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AASF,eAAO,MAAM,aAAa,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,YAAY,CA4BnF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,YAAY,EAAE,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MA6B3I,CAAC;AAaF,eAAO,MAAM,SAAS,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAe/G,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAetH,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAgBrH,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAyBxH,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAsBrH,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAarH,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAqBxH,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAErH,CAAC;AA0BF,eAAO,MAAM,UAAU,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAehH,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAiB9G,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAiB9G,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,QAAQ,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,SAAS,gBAAgB,EAAE,UAAU,MAAM,EAAE,KAAG,MAqC/G,CAAC"}

package/dist/cli/commands/export.js

@@ -3,6 +3,7 @@ import { loadDef } from "../utils/load-schema.js";
 import { resolveSchemaPath } from "../utils/resolve-schema.js";
 import path from "path";
 import { UsageError } from "../../errors.js";
+import { isRequired, isTransform, printZodTypeDts } from "../utils/printer.js";
 export const exportFormatsNames = [
     "docker-env",
     "docker-args",
@@ -15,6 +16,7 @@ export const exportFormatsNames = [
     "json",
     "ts",
     "js",
+    "types",
 ];
 const shellEscape = (value) => {
     if (value.length === 0) {
@@ -32,6 +34,9 @@ export const exportCommand = async (options) => {
     if (options.serializeTyped && !["js", "ts", "json"].includes(options.format)) {
         throw new UsageError("--serialize-typed is only valid for js, ts and json exports");
     }
+    if (options.format === "types" && options.source) {
+        throw new UsageError("--source is not applicable to the 'types' export format");
+    }
     const schemaPath = resolveSchemaPath(options?.schema);
     const envDef = (await loadDef(schemaPath));
     const warnings = [];
@@ -66,6 +71,8 @@ export const contentByFormat = (format, envDef, options, warnings) => {
             return exportDockerArgs(envDef, options, warnings);
         case "docker-env":
             return exportDockerEnv(envDef, options, warnings);
+        case "types":
+            return exportDts(envDef, options, warnings);
         default:
             throw new UsageError(`Unsupported format: ${format}`);
     }
@@ -265,4 +272,43 @@ export const exportJs = (envDef, options, warnings) => {
     }
     return `export const env = {\n${middle.join("\n")}\n};`;
 };
+export const exportDts = (envDef, options, warnings) => {
+    const middle = [];
+    let transformedCount = 0;
+    for (const key of Object.keys(envDef.def)) {
+        const type = printZodTypeDts(envDef.def[key].schema.def);
+        const optional = isRequired(envDef.def[key].schema.def) ? "" : "?";
+        const transform = isTransform(envDef.def[key].schema.def);
+        const secret = envDef.def[key].secret;
+        const required = isRequired(envDef.def[key].schema.def);
+        const description = envDef.def[key].description;
+        let comment = `    /**\n     * @env ${key}\n`;
+        if (secret)
+            comment += `     * @secret\n`;
+        if (required)
+            comment += `     * @required\n`;
+        if (description)
+            comment += `     * ${description}\n`;
+        if (transform) {
+            comment += `     *
+     * ⚠️ TRANSFORMED ENV VARIABLE
+     *
+     * Runtime type differs from declared type.
+     * Do NOT trust this type without checking the schema.
+     *
+     * @dnl-transform\n`;
+        }
+        comment += `     */`;
+        middle.push(comment);
+        middle.push(`    ${key}${optional}: ${type};`);
+        if (transform) {
+            transformedCount++;
+            warnings.push(`  - ${key} (@dnl-transform): runtime type differs from exported type.`);
+        }
+    }
+    if (transformedCount > 0) {
+        warnings.push(`⚠️  ${transformedCount} transformed variable detected. See @dnl-transform annotations.`);
+    }
+    return `export interface Env {\n${middle.join("\n")}\n}`;
+};
 // #endregion serialisation json/ts/js

package/dist/cli/commands/generate.d.ts

@@ -1,5 +1,5 @@
-export type GenerateCliOptions = {
-    schema?: string;
+import { ProgramCliOptions } from "./program.js";
+export type GenerateCliOptions = ProgramCliOptions & {
     out?: string;
     includeSecret?: boolean;
     force?: boolean;

package/dist/cli/commands/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,kBAAkB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AACF,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,OAAO,kBAAkB,GAAG,SAAS,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA6BrH,CAAC"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AACF,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,OAAO,kBAAkB,GAAG,SAAS,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA6BrH,CAAC"}

package/dist/cli/commands/infer.d.ts

@@ -0,0 +1,15 @@
+export type InferCliOptions = {
+    source?: string;
+    out?: string;
+    force?: boolean;
+    dontGuessSecret?: boolean;
+    verbose?: boolean;
+};
+export type InferResult = {
+    content: string;
+    out: string;
+    warnings: string[];
+    verbose?: Array<string>;
+};
+export declare const inferCommand: (opts?: InferCliOptions | undefined) => Promise<InferResult>;
+//# sourceMappingURL=infer.d.ts.map

package/dist/cli/commands/infer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/infer.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,eAAe,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,OAAO,eAAe,GAAG,SAAS,KAAG,OAAO,CAAC,WAAW,CA+D1F,CAAC"}

package/dist/cli/commands/infer.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import dnl from "../../index.js";
+import { guessSecret } from "../../infer/helpers.js";
+import { infer } from "../utils/infer-schema.js";
+import fs from "node:fs";
+import { ExportError } from "../../errors.js";
+export const inferCommand = async (opts) => {
+    const source = path.resolve(process.cwd(), opts?.source ?? ".env");
+    if (!fs.existsSync(source)) {
+        throw new ExportError(`Source env file not found: ${source}`);
+    }
+    const out = opts?.out ?? "env.dnl.ts";
+    const target = path.resolve(process.cwd(), out);
+    if (fs.existsSync(target) && !opts?.force) {
+        throw new ExportError(`${out} already exists. Use --force to overwrite.`);
+    }
+    const env = dnl.readEnvFile(source);
+    const lines = [];
+    const warnings = [];
+    const importedSchemas = [];
+    const verbose = [];
+    lines.push(`// ⚠️ This file was generated by dotenv-never-lies`);
+    lines.push(`// Review and adjust schemas, descriptions and secrets before using`);
+    lines.push("");
+    lines.push(`import { z } from "zod";`);
+    lines.push(`import { define } from "@romaintaillandier1978/dotenv-never-lies";`);
+    lines.push("");
+    lines.push(`export default define({`);
+    for (const [key, value] of Object.entries(env)) {
+        const isValidIdentifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key);
+        const safeKey = isValidIdentifier ? key : JSON.stringify(key);
+        if (!isValidIdentifier) {
+            warnings.push(`Key ${key} is not a valid identifier. It has been escaped to ${safeKey}.`);
+        }
+        lines.push(`    ${safeKey}: {`);
+        lines.push(`        description: "TODO",`);
+        if (value === undefined) {
+            lines.push(`        schema: z.string().optional(),`);
+        }
+        else {
+            const localWarnings = [];
+            const schema = infer(key, value, importedSchemas, verbose, localWarnings);
+            for (const warning of localWarnings) {
+                lines.push("        // " + warning);
+            }
+            lines.push(`        schema: ${schema},`);
+        }
+        if (!opts?.dontGuessSecret && guessSecret(key)) {
+            lines.push(`        secret: true, //  ⚠️  inferred as secret`);
+            verbose.push(`    -> inferred as secret`);
+            warnings.push(`${key} inferred as secret`);
+        }
+        lines.push(`    },`);
+    }
+    lines.push(`});`);
+    // insert the imported schemas at the top of the file
+    insertImports(lines, importedSchemas);
+    return {
+        content: lines.join("\n"),
+        out: target,
+        warnings: [...warnings, "Generated schema is a prototype. Review schemas, descriptions and secrets before using."],
+        verbose,
+    };
+};
+const insertImports = (lines, imports) => {
+    if (!imports || imports.length === 0)
+        return;
+    const byFrom = new Map();
+    for (const imp of imports) {
+        const current = byFrom.get(imp.from) ?? new Set();
+        current.add(imp.name);
+        byFrom.set(imp.from, current);
+    }
+    const importLines = [];
+    // tri par 'from' pour stabilité
+    const froms = Array.from(byFrom.keys()).sort();
+    for (const from of froms) {
+        const names = Array.from(byFrom.get(from) ?? new Set()).sort();
+        if (names.length === 0)
+            continue;
+        importLines.push(`import { ${names.join(", ")} } from ${JSON.stringify(from)};`);
+    }
+    if (importLines.length === 0)
+        return;
+    lines.splice(5, 0, ...importLines);
+};

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,15 @@
+import { ProgramCliOptions } from "./program.js";
+export type initCliOptions = ProgramCliOptions & {
+    out?: string;
+    includeSecret?: boolean;
+    force?: boolean;
+};
+export type InitResult = {
+    content: string;
+    out: string;
+};
+export declare const initCommand: (opts?: initCliOptions | undefined) => Promise<{
+    content: string;
+    out: string;
+}>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AACF,MAAM,MAAM,UAAU,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,OAAO,cAAc,GAAG,SAAS,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA6B7G,CAAC"}

package/dist/cli/commands/init.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadDef } from "../utils/load-schema.js";
+import { resolveSchemaPath } from "../utils/resolve-schema.js";
+import { getDefaultEnvValue } from "../utils/printer.js";
+import { ExportError } from "../../errors.js";
+export const initCommand = async (opts) => {
+    const outFile = opts?.out ?? ".env";
+    const target = path.resolve(process.cwd(), outFile);
+    if (fs.existsSync(target) && !opts?.force) {
+        throw new ExportError(`${outFile} already exists. Use --force to overwrite.`);
+    }
+    const schemaPath = resolveSchemaPath(opts?.schema);
+    const envDef = (await loadDef(schemaPath));
+    const lines = [];
+    for (const [key, def] of Object.entries(envDef.def)) {
+        const typedDef = def;
+        if (typedDef.description) {
+            lines.push(`# ${typedDef.description}`);
+        }
+        const defaultValue = getDefaultEnvValue(typedDef.schema.def);
+        lines.push(`${key}=${defaultValue ?? ""}`);
+        lines.push(""); // blank line
+    }
+    const output = lines.join("\n");
+    return {
+        content: output,
+        out: target,
+    };
+};

package/dist/cli/commands/program.d.ts

@@ -0,0 +1,4 @@
+export type ProgramCliOptions = {
+    schema?: string;
+};
+//# sourceMappingURL=program.d.ts.map

package/dist/cli/commands/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/program.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/dist/cli/commands/program.js

@@ -0,0 +1 @@
+export {};