@xlameiro/env-typegen 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.4
+
+### Patch Changes
+
+- ad8f00d: Fix six QA-identified deficiencies in CLI behaviour and documentation
+  - **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.
+  - **D2**: Document multi-generator output suffix convention in `--output` / `-o` help text (e.g. `env.generated.typescript.ts`, `env.generated.zod.ts`).
+  - **D3**: Add "Config file:" section to `--help` describing auto-discovery order (`.mjs → .js → .ts`), CLI flag override, and `defineConfig()` tip.
+  - **D4**: Expand plugin load error to include the full expected interface shape (`name`, `transformSource?`, `transformReport?`, `transformContract?`) so users know exactly what to export.
+  - **D5**: Add "Exit codes:" section to all four help texts (`generate`, `check`, `diff`, `doctor`).
+  - **D6**: Fix `--watch` mode not propagating `output` path changes when config is reloaded — `handleConfigChange` now updates `runOptions.output` alongside `generators`, `format`, and `inferenceRules`.
+
+## 0.1.3
+
+### Patch Changes
+
+- Refresh package and site documentation for the validation suite (`check`, `diff`, `doctor`), cloud snapshot sources, and plugin-based extension points. Expand public API examples to include `runValidationCommand`, `loadCloudSource`, and plugin loading helpers.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -1,22 +1,21 @@
 # env-typegen
 
-> From `.env.example` to TypeScript in one command.
+> From `.env.example` to typed outputs and contract-based environment governance.
 
 [![npm version](https://badge.fury.io/js/%40xlameiro%2Fenv-typegen.svg)](https://npmjs.com/package/@xlameiro/env-typegen)
 [![CI](https://github.com/xlameiro/env-typegen/actions/workflows/ci.yml/badge.svg)](https://github.com/xlameiro/env-typegen/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
 
-## What it does
+## What this package does
 
-`env-typegen` reads `.env.example` files and automatically generates:
+`@xlameiro/env-typegen` reads `.env.example` and helps you:
 
-- TypeScript types (`type EnvVars = { PORT: number; DATABASE_URL: string }`)
-- Zod v4 schemas (`z.object({ PORT: z.coerce.number() })`)
-- `@t3-oss/env-nextjs` `createEnv` configuration
-- `.d.ts` declaration files that augment `NodeJS.ProcessEnv`
+- generate TypeScript, Zod, t3-env, and declaration outputs
+- validate real env files against explicit contracts
+- detect drift across multiple targets
+- produce CI-friendly JSON diagnostics
 
-## Install
+## Installation
 
 ```bash
 pnpm add -D @xlameiro/env-typegen
@@ -27,73 +26,117 @@ npm install --save-dev @xlameiro/env-typegen
 ## Quick Start
 
 ```bash
-# Generate all outputs (default: typescript + zod + t3 + declaration)
+# Generate all outputs by default
 npx env-typegen --input .env.example --output src/env.generated.ts
 
-# Generate only a Zod schema
+# Generate only Zod schema
 npx env-typegen -i .env.example -o src/env.schema.ts -g zod
 
-# Generate multiple outputs explicitly
-npx env-typegen -i .env.example -o src/env.ts -f typescript -f zod
+# Watch mode
+npx env-typegen -i .env.example -o src/env.generated.ts --watch
+```
+
+## Generator formats
 
-# Generate without running Prettier
-npx env-typegen -i .env.example -o src/env.ts --no-format
+| Value                | Output                                       |
+| -------------------- | -------------------------------------------- |
+| `ts` or `typescript` | TypeScript env types                         |
+| `zod`                | Zod v4 schema                                |
+| `t3`                 | `@t3-oss/env-nextjs` `createEnv(...)` config |
+| `declaration`        | Ambient `.d.ts` env declaration              |
 
-# Watch mode — regenerate on every change
-npx env-typegen -i .env.example -o src/env.ts --watch
+Multiple outputs in one run:
+
+```bash
+npx env-typegen -i .env.example -o src/env.ts -f typescript -f zod -f declaration
 ```
 
-## Generator formats
+## Validation and governance commands
 
-Use `-f` / `--format` (or `-g` / `--generator` alias):
+```bash
+# Validate one source
+npx env-typegen check --env .env --contract env.contract.ts
 
-| Value                | Meaning                              |
-| -------------------- | ------------------------------------ |
-| `ts` or `typescript` | Generate TypeScript types            |
-| `zod`                | Generate Zod schema                  |
-| `t3`                 | Generate `@t3-oss/env-nextjs` config |
-| `declaration`        | Generate `.d.ts` declaration         |
+# Compare drift across sources
+npx env-typegen diff --targets .env,.env.example,.env.production --contract env.contract.ts
 
-## Programmatic API
+# Aggregated diagnostics
+npx env-typegen doctor --env .env --targets .env,.env.example,.env.production --contract env.contract.ts
+```
 
-```ts
-import { runGenerate, parseEnvFile, generateTypeScriptTypes } from "@xlameiro/env-typegen";
-
-// High-level: full pipeline
-await runGenerate({
-  input: ".env.example",
-  output: "src/env.generated.ts",
-  generators: ["typescript"],
-  format: true,
-});
-
-// Low-level: parse then generate individually
-const parsed = parseEnvFile(".env.example");
-const ts = generateTypeScriptTypes(parsed);
+JSON output for CI:
+
+```bash
+npx env-typegen check --env .env --json --output-file reports/env-check.json
+```
+
+Strict mode is enabled by default. Use `--no-strict` to downgrade undeclared variables to warnings.
+
+## Cloud snapshots
+
+Validation commands can include cloud snapshot sources:
+
+```bash
+npx env-typegen check --cloud-provider vercel --cloud-file vercel-env.json --contract env.contract.ts
+npx env-typegen diff --cloud-provider cloudflare --cloud-file cloudflare-env.json --contract env.contract.ts
+npx env-typegen doctor --cloud-provider aws --cloud-file aws-env.json --contract env.contract.ts
 ```
 
-## Configuration
+Supported providers: `vercel`, `cloudflare`, `aws`.
 
-Create `env-typegen.config.ts` at your project root:
+## Plugin hooks
+
+Use plugins to customize validation behavior:
+
+- `transformContract`
+- `transformSource`
+- `transformReport`
+
+Load plugins with repeated `--plugin` flags or via `plugins` in `env-typegen.config.ts`.
+
+## Programmatic API
 
 ```ts
-import { defineConfig } from "@xlameiro/env-typegen";
-
-export default defineConfig({
-  input: ".env.example",
-  output: "src/env.generated.ts",
-  generators: ["typescript", "zod"],
-  format: true,
-});
+import {
+  runGenerate,
+  runValidationCommand,
+  parseEnvFile,
+  generateTypeScriptTypes,
+  loadCloudSource,
+  loadPlugins,
+} from "@xlameiro/env-typegen";
 ```
 
-## Status
+## Typical adoption path
 
-`env-typegen` is actively maintained and published on npm.
+1. Start with generation-only output (`ts`, `zod`).
+2. Add `check` in CI for contract enforcement.
+3. Add `diff` and `doctor` for drift prevention.
+4. Add cloud snapshots and plugins for advanced workflows.
+
+## FAQ
+
+### Is this package only for Next.js?
 
-## Changelog
+No. It is framework-agnostic. The `t3` generator is optional.
 
-See [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
+### Can I use it without a contract file?
+
+Yes, but explicit contracts are recommended for governance and CI reliability.
+
+### Which command should I run in CI?
+
+Start with `check`. Add `diff` or `doctor` as your pipeline maturity grows.
+
+## Docs and references
+
+- Website docs source: [`/content/docs`](../../content/docs)
+- Package docs index: [`/packages/env-typegen/docs`](./docs)
+- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
+
+## Status
+
+`env-typegen` is actively maintained and published on npm.
 
 ## License