@xlameiro/env-typegen 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +67 -105
  3. package/dist/cli.js +424 -329
  4. package/dist/cli.js.map +1 -1
  5. package/dist/index.cjs +419 -334
  6. package/dist/index.cjs.map +1 -1
  7. package/dist/index.js +419 -334
  8. package/dist/index.js.map +1 -1
  9. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.4
4
+
5
+ ### Patch Changes
6
+
7
+ - ad8f00d: Fix six QA-identified deficiencies in CLI behaviour and documentation
8
+ - **D1 (critical)**: Fix crash when `.ts` config file is present — `loadConfig()` now throws an actionable error with a code snippet instead of silently failing. `CONFIG_FILE_NAMES` load order changed to `.mjs → .js → .ts` to prefer simpler formats first.
9
+ - **D2**: Document multi-generator output suffix convention in `--output` / `-o` help text (e.g. `env.generated.typescript.ts`, `env.generated.zod.ts`).
10
+ - **D3**: Add "Config file:" section to `--help` describing auto-discovery order (`.mjs → .js → .ts`), CLI flag override, and `defineConfig()` tip.
11
+ - **D4**: Expand plugin load error to include the full expected interface shape (`name`, `transformSource?`, `transformReport?`, `transformContract?`) so users know exactly what to export.
12
+ - **D5**: Add "Exit codes:" section to all four help texts (`generate`, `check`, `diff`, `doctor`).
13
+ - **D6**: Fix `--watch` mode not propagating `output` path changes when config is reloaded — `handleConfigChange` now updates `runOptions.output` alongside `generators`, `format`, and `inferenceRules`.
14
+
3
15
  ## 0.1.3
4
16
 
5
17
  ### Patch Changes
package/README.md CHANGED
@@ -1,22 +1,21 @@
1
1
  # env-typegen
2
2
 
3
- > From `.env.example` to TypeScript in one command.
3
+ > From `.env.example` to typed outputs and contract-based environment governance.
4
4
 
5
5
  [![npm version](https://badge.fury.io/js/%40xlameiro%2Fenv-typegen.svg)](https://npmjs.com/package/@xlameiro/env-typegen)
6
6
  [![CI](https://github.com/xlameiro/env-typegen/actions/workflows/ci.yml/badge.svg)](https://github.com/xlameiro/env-typegen/actions/workflows/ci.yml)
7
7
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
9
8
 
10
- ## What it does
9
+ ## What this package does
11
10
 
12
- `env-typegen` reads `.env.example` files and automatically generates:
11
+ `@xlameiro/env-typegen` reads `.env.example` and helps you:
13
12
 
14
- - TypeScript types (`type EnvVars = { PORT: number; DATABASE_URL: string }`)
15
- - Zod v4 schemas (`z.object({ PORT: z.coerce.number() })`)
16
- - `@t3-oss/env-nextjs` `createEnv` configuration
17
- - `.d.ts` declaration files that augment `NodeJS.ProcessEnv`
13
+ - generate TypeScript, Zod, t3-env, and declaration outputs
14
+ - validate real env files against explicit contracts
15
+ - detect drift across multiple targets
16
+ - produce CI-friendly JSON diagnostics
18
17
 
19
- ## Install
18
+ ## Installation
20
19
 
21
20
  ```bash
22
21
  pnpm add -D @xlameiro/env-typegen
@@ -27,69 +26,55 @@ npm install --save-dev @xlameiro/env-typegen
27
26
  ## Quick Start
28
27
 
29
28
  ```bash
30
- # Generate all outputs (default: typescript + zod + t3 + declaration)
29
+ # Generate all outputs by default
31
30
  npx env-typegen --input .env.example --output src/env.generated.ts
32
31
 
33
- # Generate only a Zod schema
32
+ # Generate only Zod schema
34
33
  npx env-typegen -i .env.example -o src/env.schema.ts -g zod
35
34
 
36
- # Generate multiple outputs explicitly
37
- npx env-typegen -i .env.example -o src/env.ts -f typescript -f zod
38
-
39
- # Generate without running Prettier
40
- npx env-typegen -i .env.example -o src/env.ts --no-format
41
-
42
- # Watch mode — regenerate on every change
43
- npx env-typegen -i .env.example -o src/env.ts --watch
44
-
45
- # Validate one env source against a contract (strict by default)
46
- npx env-typegen check --env .env --contract env.contract.ts
47
-
48
- # Compare drift across multiple env files
49
- npx env-typegen diff --targets .env,.env.example,.env.production --contract env.contract.ts
50
-
51
- # Full diagnostics (check + diff + recommendations)
52
- npx env-typegen doctor --env .env --targets .env,.env.example,.env.production --contract env.contract.ts
53
-
54
- # Machine-readable report for CI pipelines
55
- npx env-typegen check --env .env --json --output-file reports/env-check.json
35
+ # Watch mode
36
+ npx env-typegen -i .env.example -o src/env.generated.ts --watch
56
37
  ```
57
38
 
58
- All paths (`--env`, `--contract`, `--targets`, and `--output-file`) are resolved from your current working directory.
59
-
60
39
  ## Generator formats
61
40
 
62
- Use `-f` / `--format` (or `-g` / `--generator` alias):
41
+ | Value | Output |
42
+ | -------------------- | -------------------------------------------- |
43
+ | `ts` or `typescript` | TypeScript env types |
44
+ | `zod` | Zod v4 schema |
45
+ | `t3` | `@t3-oss/env-nextjs` `createEnv(...)` config |
46
+ | `declaration` | Ambient `.d.ts` env declaration |
63
47
 
64
- | Value | Meaning |
65
- | -------------------- | ------------------------------------ |
66
- | `ts` or `typescript` | Generate TypeScript types |
67
- | `zod` | Generate Zod schema |
68
- | `t3` | Generate `@t3-oss/env-nextjs` config |
69
- | `declaration` | Generate `.d.ts` declaration |
48
+ Multiple outputs in one run:
70
49
 
71
- ## Validation commands
50
+ ```bash
51
+ npx env-typegen -i .env.example -o src/env.ts -f typescript -f zod -f declaration
52
+ ```
72
53
 
73
- `env-typegen` also includes governance-focused commands:
54
+ ## Validation and governance commands
74
55
 
75
- - `check` — validates one env source against the contract
76
- - `diff` — compares env sources and detects configuration drift
77
- - `doctor` — aggregates findings and prints remediation suggestions
56
+ ```bash
57
+ # Validate one source
58
+ npx env-typegen check --env .env --contract env.contract.ts
78
59
 
79
- ### Strict mode
60
+ # Compare drift across sources
61
+ npx env-typegen diff --targets .env,.env.example,.env.production --contract env.contract.ts
80
62
 
81
- - Strict mode is enabled by default for validation commands.
82
- - Use `--no-strict` to downgrade undeclared variables to warnings.
63
+ # Aggregated diagnostics
64
+ npx env-typegen doctor --env .env --targets .env,.env.example,.env.production --contract env.contract.ts
65
+ ```
66
+
67
+ JSON output for CI:
83
68
 
84
- ### JSON output
69
+ ```bash
70
+ npx env-typegen check --env .env --json --output-file reports/env-check.json
71
+ ```
85
72
 
86
- - `--json` outputs compact JSON
87
- - `--json=pretty` outputs formatted JSON
88
- - `--output-file <path>` writes the JSON report to disk
73
+ Strict mode is enabled by default. Use `--no-strict` to downgrade undeclared variables to warnings.
89
74
 
90
- ### Cloud snapshots
75
+ ## Cloud snapshots
91
76
 
92
- Validation commands can include cloud snapshot files as additional sources:
77
+ Validation commands can include cloud snapshot sources:
93
78
 
94
79
  ```bash
95
80
  npx env-typegen check --cloud-provider vercel --cloud-file vercel-env.json --contract env.contract.ts
@@ -99,15 +84,15 @@ npx env-typegen doctor --cloud-provider aws --cloud-file aws-env.json --contract
99
84
 
100
85
  Supported providers: `vercel`, `cloudflare`, `aws`.
101
86
 
102
- ### Plugins
87
+ ## Plugin hooks
103
88
 
104
- Use plugins to extend validation behavior:
89
+ Use plugins to customize validation behavior:
105
90
 
106
- - `transformContract` — mutate the loaded contract before validation
107
- - `transformSource` — mutate environment values per source
108
- - `transformReport` — enrich final validation reports
91
+ - `transformContract`
92
+ - `transformSource`
93
+ - `transformReport`
109
94
 
110
- Load plugins with repeated `--plugin` flags or from `env-typegen.config.ts` (`plugins` field).
95
+ Load plugins with repeated `--plugin` flags or via `plugins` in `env-typegen.config.ts`.
111
96
 
112
97
  ## Programmatic API
113
98
 
@@ -120,61 +105,38 @@ import {
120
105
  loadCloudSource,
121
106
  loadPlugins,
122
107
  } from "@xlameiro/env-typegen";
123
-
124
- // High-level: full pipeline
125
- await runGenerate({
126
- input: ".env.example",
127
- output: "src/env.generated.ts",
128
- generators: ["typescript"],
129
- format: true,
130
- });
131
-
132
- // Low-level: parse then generate individually
133
- const parsed = parseEnvFile(".env.example");
134
- const ts = generateTypeScriptTypes(parsed);
135
-
136
- // Run validation commands programmatically
137
- const exitCode = await runValidationCommand({
138
- command: "check",
139
- argv: ["--env", ".env", "--contract", "env.contract.ts", "--json"],
140
- });
141
-
142
- // Load cloud snapshots and plugins in custom integrations
143
- const cloudValues = await loadCloudSource({ provider: "vercel", filePath: "vercel-env.json" });
144
- const plugins = await loadPlugins({ pluginPaths: ["./plugins/custom.mjs"] });
145
108
  ```
146
109
 
147
- ## Configuration
110
+ ## Typical adoption path
148
111
 
149
- Create `env-typegen.config.ts` at your project root:
112
+ 1. Start with generation-only output (`ts`, `zod`).
113
+ 2. Add `check` in CI for contract enforcement.
114
+ 3. Add `diff` and `doctor` for drift prevention.
115
+ 4. Add cloud snapshots and plugins for advanced workflows.
150
116
 
151
- ```ts
152
- import { defineConfig } from "@xlameiro/env-typegen";
153
-
154
- export default defineConfig({
155
- input: ".env.example",
156
- output: "src/env.generated.ts",
157
- generators: ["typescript", "zod"],
158
- format: true,
159
- schemaFile: "env.contract.ts",
160
- strict: true,
161
- diffTargets: [".env", ".env.example", ".env.production"],
162
- plugins: ["./plugins/custom-validator.mjs"],
163
- });
164
- ```
117
+ ## FAQ
165
118
 
166
- ## Documentation
119
+ ### Is this package only for Next.js?
167
120
 
168
- - Fumadocs source in repo: [`/content/docs`](../../content/docs)
169
- - Package markdown docs: [`/packages/env-typegen/docs`](./docs)
121
+ No. It is framework-agnostic. The `t3` generator is optional.
170
122
 
171
- ## Status
123
+ ### Can I use it without a contract file?
172
124
 
173
- `env-typegen` is actively maintained and published on npm.
125
+ Yes, but explicit contracts are recommended for governance and CI reliability.
126
+
127
+ ### Which command should I run in CI?
128
+
129
+ Start with `check`. Add `diff` or `doctor` as your pipeline maturity grows.
174
130
 
175
- ## Changelog
131
+ ## Docs and references
176
132
 
177
- See [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
133
+ - Website docs source: [`/content/docs`](../../content/docs)
134
+ - Package docs index: [`/packages/env-typegen/docs`](./docs)
135
+ - Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
136
+
137
+ ## Status
138
+
139
+ `env-typegen` is actively maintained and published on npm.
178
140
 
179
141
  ## License
180
142