@xlameiro/env-typegen 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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
+
+- Refresh the published npm package metadata and README to match the current repository documentation.
+
 All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) and uses
@@ -7,7 +19,39 @@ This project adheres to [Semantic Versioning](https://semver.org/) and uses
 
 <!-- Releases are added automatically by `changeset version` -->
 
-## [0.1.0] — 2026-03-16
+## [0.1.1] — 2026-03-17
+
+### Fixed
+
+- **A1** — VERSION was hardcoded as `"0.1.0"` in `cli.ts`; now read dynamically from `package.json` via `createRequire` so it stays in sync without manual edits.
+- **A2** — Double-quotes in `@description` annotations were not escaped in the t3-generator output, corrupting the generated `createEnv(...)` call. Fixed with `.replace(/"/g, '\\"')`.
+- **A3** — Prettier parse errors in `formatOutput` were silently swallowed; a `console.warn` is now emitted before the raw-content fallback.
+- **A4** — Watch mode only listened for `"change"` events; it now also handles `"add"` and `"unlink"` so editor save-with-delete patterns are covered.
+- **A5** — Config file changes during `--watch` were silently ignored; a second chokidar watcher now monitors the config file and reloads it on change.
+- **C1** — `formatOutput` (Prettier) was called unnecessarily in dry-run mode; formatting now runs only when actually writing to disk.
+- **C3** — Removed duplicate alias exports (`generateTypeScript`, `generateZod`); the canonical names `generateTypeScriptTypes` and `generateZodSchema` are the only public exports.
+- **E1–E3** — README badge URLs had `YOUR_USERNAME` placeholders; replaced with the real GitHub/npm identifiers. Package name aligned to `@xlameiro/env-typegen` throughout all docs.
+- **E4** — README `--format` example was misleading; corrected to use `--generator`/`-f` for generator selection and document `--no-format` for disabling Prettier.
+- **E5** — `parseEnvFile` was documented as `async`/awaitable but is synchronous; removed erroneous `await` from all examples.
+- **DRY** — `CONFIG_FILE_NAMES` was duplicated between `config.ts` and `watch.ts`; exported from `config.ts` and imported in `watch.ts`.
+
+### Added
+
+- **B1** — `EnvTypegenConfig.input` now accepts `string | string[]`; CLI `--input`/`-i` can be repeated to process multiple `.env` files in one run.
+- **B2** — `inferenceRules?: InferenceRule[]` added to `EnvTypegenConfig` and `RunGenerateOptions`; custom rules are prepended before the built-in ruleset.
+- **B3** — Default generators changed from `["typescript"]` to all four: `["typescript", "zod", "t3", "declaration"]`, matching the spec.
+- **B4** — Dry-run mode now prints each generated output block to stdout so users can preview content without touching the filesystem.
+- **B5** — Watch mode debounces rapid file-change events (200 ms) to prevent multiple simultaneous pipeline runs on editor autosave.
+
+### Tests
+
+- Regression test for double-quotes in t3-generator descriptions (A2).
+- CLI version tests read expected version from `package.json` (A1).
+- Four `loadConfig()` unit tests with temp-dir fixtures (no stale state).
+- Dry-run stdout spy test verifying preview content appears (B4).
+- Integration tests expanded to five end-to-end scenarios via `execSync` against the built `dist/cli.js`.
+
+[0.1.1]: https://github.com/xlameiro/env-typegen/compare/packages/env-typegen@0.1.0...packages/env-typegen@0.1.1
 
 ### Added
 
@@ -54,4 +98,4 @@ This project adheres to [Semantic Versioning](https://semver.org/) and uses
 - Full TSDoc on every public export in `src/index.ts`
 - README with Quick Start (CLI examples), Programmatic API, and Configuration sections
 
-[0.1.0]: https://github.com/YOUR_USERNAME/env-typegen/releases/tag/v0.1.0
+[0.1.0]: https://github.com/xlameiro/env-typegen/releases/tag/v0.1.0

package/README.md

@@ -2,8 +2,8 @@
 
 > From `.env.example` to TypeScript in one command.
 
-[![npm version](https://badge.fury.io/js/env-typegen.svg)](https://npmjs.com/package/env-typegen)
-[![CI](https://github.com/YOUR_USERNAME/env-typegen/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/env-typegen/actions/workflows/ci.yml)
+[![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/)
 
@@ -11,31 +11,115 @@
 
 `env-typegen` reads `.env.example` files and automatically generates:
 
-- TypeScript types (`type Env = { PORT: number; DATABASE_URL: string }`)
+- 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`
 
+## Install
+
+```bash
+pnpm add -D @xlameiro/env-typegen
+# or
+npm install --save-dev @xlameiro/env-typegen
+```
+
 ## Quick Start
 
 ```bash
-# Generate TypeScript types (default)
+# Generate all outputs (default: typescript + zod + t3 + declaration)
 npx env-typegen --input .env.example --output src/env.generated.ts
 
-# Generate a Zod schema
+# Generate only a Zod schema
 npx env-typegen -i .env.example -o src/env.schema.ts -g zod
 
-# Generate multiple outputs and format with Prettier
-npx env-typegen -i .env.example -o src/env.ts -g typescript -g zod --format
+# Generate multiple outputs explicitly
+npx env-typegen -i .env.example -o src/env.ts -f typescript -f zod
+
+# Generate without running Prettier
+npx env-typegen -i .env.example -o src/env.ts --no-format
 
 # Watch mode — regenerate on every change
 npx env-typegen -i .env.example -o src/env.ts --watch
+
+# Validate one env source against a contract (strict by default)
+npx env-typegen check --env .env --contract env.contract.ts
+
+# Compare drift across multiple env files
+npx env-typegen diff --targets .env,.env.example,.env.production --contract env.contract.ts
+
+# Full diagnostics (check + diff + recommendations)
+npx env-typegen doctor --env .env --targets .env,.env.example,.env.production --contract env.contract.ts
+
+# Machine-readable report for CI pipelines
+npx env-typegen check --env .env --json --output-file reports/env-check.json
 ```
 
+All paths (`--env`, `--contract`, `--targets`, and `--output-file`) are resolved from your current working directory.
+
+## Generator formats
+
+Use `-f` / `--format` (or `-g` / `--generator` alias):
+
+| Value                | Meaning                              |
+| -------------------- | ------------------------------------ |
+| `ts` or `typescript` | Generate TypeScript types            |
+| `zod`                | Generate Zod schema                  |
+| `t3`                 | Generate `@t3-oss/env-nextjs` config |
+| `declaration`        | Generate `.d.ts` declaration         |
+
+## Validation commands
+
+`env-typegen` also includes governance-focused commands:
+
+- `check` — validates one env source against the contract
+- `diff` — compares env sources and detects configuration drift
+- `doctor` — aggregates findings and prints remediation suggestions
+
+### Strict mode
+
+- Strict mode is enabled by default for validation commands.
+- Use `--no-strict` to downgrade undeclared variables to warnings.
+
+### JSON output
+
+- `--json` outputs compact JSON
+- `--json=pretty` outputs formatted JSON
+- `--output-file <path>` writes the JSON report to disk
+
+### Cloud snapshots
+
+Validation commands can include cloud snapshot files as additional 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
+```
+
+Supported providers: `vercel`, `cloudflare`, `aws`.
+
+### Plugins
+
+Use plugins to extend validation behavior:
+
+- `transformContract` — mutate the loaded contract before validation
+- `transformSource` — mutate environment values per source
+- `transformReport` — enrich final validation reports
+
+Load plugins with repeated `--plugin` flags or from `env-typegen.config.ts` (`plugins` field).
+
 ## Programmatic API
 
 ```ts
-import { runGenerate, parseEnvFile, generateTypeScriptTypes } from "env-typegen";
+import {
+  runGenerate,
+  runValidationCommand,
+  parseEnvFile,
+  generateTypeScriptTypes,
+  loadCloudSource,
+  loadPlugins,
+} from "@xlameiro/env-typegen";
 
 // High-level: full pipeline
 await runGenerate({
@@ -46,8 +130,18 @@ await runGenerate({
 });
 
 // Low-level: parse then generate individually
-const parsed = await parseEnvFile(".env.example");
+const parsed = parseEnvFile(".env.example");
 const ts = generateTypeScriptTypes(parsed);
+
+// Run validation commands programmatically
+const exitCode = await runValidationCommand({
+  command: "check",
+  argv: ["--env", ".env", "--contract", "env.contract.ts", "--json"],
+});
+
+// Load cloud snapshots and plugins in custom integrations
+const cloudValues = await loadCloudSource({ provider: "vercel", filePath: "vercel-env.json" });
+const plugins = await loadPlugins({ pluginPaths: ["./plugins/custom.mjs"] });
 ```
 
 ## Configuration
@@ -55,28 +149,32 @@ const ts = generateTypeScriptTypes(parsed);
 Create `env-typegen.config.ts` at your project root:
 
 ```ts
-import { defineConfig } from "env-typegen";
+import { defineConfig } from "@xlameiro/env-typegen";
 
 export default defineConfig({
   input: ".env.example",
   output: "src/env.generated.ts",
   generators: ["typescript", "zod"],
   format: true,
+  schemaFile: "env.contract.ts",
+  strict: true,
+  diffTargets: [".env", ".env.example", ".env.production"],
+  plugins: ["./plugins/custom-validator.mjs"],
 });
 ```
 
+## Documentation
+
+- Fumadocs source in repo: [`/content/docs`](../../content/docs)
+- Package markdown docs: [`/packages/env-typegen/docs`](./docs)
+
 ## Status
 
-| Phase | Description    | Status |
-| ----- | -------------- | ------ |
-| 1     | Foundation     | ✅     |
-| 2     | Parser         | ✅     |
-| 3     | Inferrer       | ✅     |
-| 4     | Generators     | ✅     |
-| 5     | Config & Utils | ✅     |
-| 6     | CLI            | ✅     |
-| 7     | Quality & Docs | ✅     |
-| 8     | Publishing     | 🔜     |
+`env-typegen` is actively maintained and published on npm.
+
+## Changelog
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
 
 ## License