@xlameiro/env-typegen 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

package/README.md

@@ -41,8 +41,22 @@ 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):
@@ -54,10 +68,58 @@ Use `-f` / `--format` (or `-g` / `--generator` alias):
 | `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 "@xlameiro/env-typegen";
+import {
+  runGenerate,
+  runValidationCommand,
+  parseEnvFile,
+  generateTypeScriptTypes,
+  loadCloudSource,
+  loadPlugins,
+} from "@xlameiro/env-typegen";
 
 // High-level: full pipeline
 await runGenerate({
@@ -70,6 +132,16 @@ await runGenerate({
 // Low-level: parse then generate individually
 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
@@ -84,9 +156,18 @@ export default defineConfig({
   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
 
 `env-typegen` is actively maintained and published on npm.