zod-envkit 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,11 +1,34 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
+All notable changes to this project will be documented in this file.  
 This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.0.2] – 2026-01-26
+
+### Added
+- `zod-envkit show` command to display environment status in a readable table (with secret masking)
+- `zod-envkit check` command to validate required variables with CI-friendly exit codes
+
+### Changed
+- CLI now also searches for `env.meta.json` in `./examples/` by default
+- CLI output and documentation updated accordingly
+
+[1.0.2]: https://www.npmjs.com/package/zod-envkit/v/1.0.2
+
+---
+
+## [1.0.1] – 2026-01-26
+
+### Changed
+- Packaging improvements for npm (ship only compiled output and docs)
+- Documentation updates
+
+[1.0.1]: https://www.npmjs.com/package/zod-envkit/v/1.0.1
+
+---
+
 ## [1.0.0] – 2026-01-26
 
 ### Added
@@ -16,11 +39,9 @@ This project follows [Semantic Versioning](https://semver.org/).
 - CLI tool to generate:
   - `.env.example`
   - `ENV.md` documentation
-- Automatic type inference for validated environment variables
 - Support for ESM and CommonJS builds
 - TypeScript declaration files (`.d.ts`) included
 - Basic test suite using Vitest
-- Clear and documented API surface
 - MIT license
 
 ### Design Decisions
@@ -29,15 +50,4 @@ This project follows [Semantic Versioning](https://semver.org/).
 - Environment variables treated as an explicit runtime contract
 - Small, framework-agnostic core
 
----
-
 [1.0.0]: https://www.npmjs.com/package/zod-envkit/v/1.0.0
-
-
-## [1.0.1] – 2026-01-26
-
-### Changed
-- Documentation and packaging improvements
-- Minor CLI/docs adjustments
-
-[1.0.1]: https://www.npmjs.com/package/zod-envkit/v/1.0.1

package/README.md

@@ -1,26 +1,28 @@
 <div align="center">
-	<br />
-	<p>
-		<img src="./zod-envkit.svg" width="546" alt="zod-envkit" /><
-	</p>
-	<br />
-	<p>
-		<a href="https://www.npmjs.com/package/zod-envkit"><img src="https://img.shields.io/npm/v/zod-envkit.svg?maxAge=100" alt="npm version" /></a>
-		<a href="https://www.npmjs.com/package/zod-envkit"><img src="https://img.shields.io/npm/dt/zod-envkit.svg?maxAge=100" alt="npm downloads" /></a>
-	</p>
-  <p align="center">
-    <b> A framework for developing bots based using discord.js. </b>
+  <br />
+  <p>
+    <img src="./zod-envkit.svg" width="546" alt="zod-envkit" />
+  </p>
+  <br />
+  <p>
+    <a href="https://www.npmjs.com/package/zod-envkit">
+      <img src="https://img.shields.io/npm/v/zod-envkit.svg?maxAge=100" alt="npm version" />
+    </a>
+    <a href="https://www.npmjs.com/package/zod-envkit">
+      <img src="https://img.shields.io/npm/dt/zod-envkit.svg?maxAge=100" alt="npm downloads" />
+    </a>
   </p>
 </div>
 
-Type-safe environment variable validation and documentation using Zod.
+Type-safe environment variable validation and documentation using **Zod**.
+
+**zod-envkit** is a small library + CLI that helps you treat environment variables as an **explicit runtime contract**, not an implicit guessing game.
 
-`zod-envkit` is a small library and CLI tool that helps you:
-- validate `process.env`
-- get **fully typed environment variables**
-- automatically generate `.env.example`
-- generate environment documentation (`ENV.md`)
-- treat environment variables as an **explicit contract**, not guesswork
+- validate `process.env` at startup
+- get fully typed environment variables
+- generate `.env.example`
+- generate readable documentation (`ENV.md`)
+- inspect and verify env state via CLI
 
 No cloud. No magic. Just code.
 
@@ -28,18 +30,19 @@ No cloud. No magic. Just code.
 
 ## Why
 
-The problem:
+Environment variables are critical, but usually poorly handled.
+
+The usual problems:
 - `process.env` is just `string | undefined`
-- environment errors often appear **only at runtime**
-- `.env.example` and documentation are often outdated or missing
+- missing or invalid variables fail **at runtime**
+- `.env.example` and docs get outdated
+- CI/CD breaks late and unpredictably
 
-The solution:
-- define your environment **once**
-- get:
-  - early validation
-  - TypeScript types
-  - up-to-date `.env.example`
-  - up-to-date documentation
+**zod-envkit** solves this by making env:
+- validated early
+- typed
+- documented
+- checkable in CI
 
 ---
 
@@ -57,7 +60,9 @@ pnpm add zod-envkit
 
 ---
 
-## Quick start
+## Library usage (runtime validation)
+
+Create a single file responsible for loading and validating env.
 
 ```ts
 import "dotenv/config";
@@ -67,7 +72,7 @@ import { loadEnv, formatZodError } from "zod-envkit";
 const EnvSchema = z.object({
   NODE_ENV: z.enum(["development", "test", "production"]),
   PORT: z.coerce.number().int().min(1).max(65535),
-  DATABASE_URL: z.string().url()
+  DATABASE_URL: z.string().url(),
 });
 
 const result = loadEnv(EnvSchema);
@@ -85,86 +90,102 @@ Now:
 * `env.PORT` is a **number**
 * `env.DATABASE_URL` is a **string**
 * TypeScript knows everything at compile time
+* your app fails fast if env is invalid
 
 ---
 
-## CLI: generate `.env.example` and `ENV.md`
+## CLI usage
+
+The CLI works from a simple metadata file: `env.meta.json`.
 
-### 1️⃣ Create `env.meta.json` in your project root
+By default, it is searched in:
+
+* `./env.meta.json`
+* `./examples/env.meta.json`
+
+---
+
+### Example `env.meta.json`
 
 ```json
 {
   "NODE_ENV": {
-    "description": "Application runtime environment",
-    "example": "development"
+    "description": "Runtime mode",
+    "example": "development",
+    "required": true
   },
   "PORT": {
-    "description": "HTTP server port",
-    "example": "3000"
+    "description": "HTTP port",
+    "example": "3000",
+    "required": true
   },
   "DATABASE_URL": {
-    "description": "PostgreSQL connection string",
-    "example": "postgresql://user:pass@localhost:5432/db"
+    "description": "Postgres connection string",
+    "example": "postgresql://user:pass@localhost:5432/db",
+    "required": true
   }
 }
 ```
 
 ---
 
-### 2️⃣ Run the CLI
+## CLI commands
+
+### Generate `.env.example` and `ENV.md`
+
+(Default behavior)
 
 ```bash
 npx zod-envkit
 ```
 
-Or locally during development:
+or explicitly:
 
 ```bash
-node dist/cli.js
+npx zod-envkit generate
 ```
 
 ---
 
-### 3️⃣ Output
+### Show current environment status
 
-#### `.env.example`
+Loads `.env`, masks secrets, and displays a readable table.
 
-```env
-# Application runtime environment
-NODE_ENV=development
+```bash
+npx zod-envkit show
+```
 
-# HTTP server port
-PORT=3000
+Example output:
 
-# PostgreSQL connection string
-DATABASE_URL=postgresql://user:pass@localhost:5432/db
-```
+* which variables are required
+* which are present
+* masked values for secrets
 
-#### `ENV.md`
+---
 
-```md
-# Environment variables
+### Validate required variables (CI-friendly)
 
-| Key | Required | Example | Description |
-|---|---:|---|---|
-| NODE_ENV | yes | development | Application runtime environment |
-| PORT | yes | 3000 | HTTP server port |
-| DATABASE_URL | yes | postgresql://... | PostgreSQL connection string |
+```bash
+npx zod-envkit check
 ```
 
+* exits with code `1` if any required variable is missing
+* perfect for CI/CD pipelines and pre-deploy checks
+
 ---
 
-## CLI options
+### CLI options
 
 ```bash
 zod-envkit --help
 ```
 
+Common flags:
+
 ```bash
-zod-envkit \
-  --config env.meta.json \
-  --out-example .env.example \
-  --out-docs ENV.md
+zod-envkit show \
+  --config examples/env.meta.json \
+  --env-file .env
 ```
 
 ---
@@ -176,6 +197,7 @@ zod-envkit \
 * ❌ no validation
 * ❌ no types
 * ❌ no documentation
+* ❌ no CI checks
 
 `zod-envkit`:
 
@@ -184,39 +206,40 @@ zod-envkit \
 * ✅ documentation
 * ✅ CLI tooling
 
-They work **great together**.
+They are designed to be used **together**.
 
 ---
 
-## Design decisions
+## Design principles
 
-* ❌ does not try to automatically parse Zod schemas
-* ❌ does not couple to any framework
-* ✅ explicit configuration over magic
-* ✅ small, predictable API
-* ✅ library + CLI, both optional
+* explicit configuration over magic
+* no framework coupling
+* small and predictable API
+* library and CLI are independent but complementary
+* environment variables are a runtime contract
 
 ---
 
 ## Roadmap
 
 * [ ] schema ↔ meta consistency checks
-* [ ] `zod-envkit check` (validation only)
-* [ ] grouping / sections in docs
-* [ ] prettier, human-friendly error output
+* [ ] grouped sections in generated docs
+* [ ] prettier, more human-friendly error output
 * [ ] JSON schema export
+* [ ] stricter validation modes for production
 
 ---
 
 ## Who is this for?
 
 * backend and fullstack projects
-* Node.js / Bun services
+* Node.js and Bun services
 * CI/CD pipelines
-* teams that treat env as part of their contract
+* teams that want env errors to fail fast, not late
 
 ---
 
 ## License
 
 MIT
+

package/dist/cli.cjs

@@ -27,6 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var import_node_fs = __toESM(require("fs"), 1);
 var import_node_path = __toESM(require("path"), 1);
 var import_commander = require("commander");
+var import_dotenv = __toESM(require("dotenv"), 1);
 
 // src/generate.ts
 function strLen(s) {
@@ -98,13 +99,111 @@ function generateEnvDocs(meta) {
 }
 
 // src/cli.ts
-var program = new import_commander.Command();
-program.name("zod-envkit").description("Generate .env.example and ENV.md from env.meta.json").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md").action((opts) => {
-  const configPath = import_node_path.default.resolve(process.cwd(), opts.config);
+function maskValue(key, value) {
+  const k = key.toUpperCase();
+  const isSecret = k.includes("TOKEN") || k.includes("SECRET") || k.includes("PASSWORD") || k.includes("API_KEY") || k.includes("KEY");
+  if (!isSecret) return value;
+  if (value.length <= 4) return "*".repeat(value.length);
+  return value.slice(0, 2) + "*".repeat(Math.max(1, value.length - 4)) + value.slice(-2);
+}
+function padCenter2(text, width) {
+  const t = text ?? "";
+  const diff = width - t.length;
+  if (diff <= 0) return t;
+  const left = Math.floor(diff / 2);
+  const right = diff - left;
+  return " ".repeat(left) + t + " ".repeat(right);
+}
+function printTable(rows, headers) {
+  const widths = {};
+  for (const h of headers) widths[h] = h.length;
+  for (const row of rows) {
+    for (const h of headers) {
+      widths[h] = Math.max(widths[h], (row[h] ?? "").length);
+    }
+  }
+  for (const h of headers) widths[h] += 2;
+  const line = "|" + headers.map((h) => " " + padCenter2(h, widths[h]) + " ").join("|") + "|";
+  const sep = "|" + headers.map((h) => ":" + "-".repeat(Math.max(3, widths[h])) + ":").join("|") + "|";
+  console.log(line);
+  console.log(sep);
+  for (const row of rows) {
+    const rowLine = "|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|";
+    console.log(rowLine);
+  }
+}
+function loadMeta(configFile) {
+  const cwd = process.cwd();
+  const candidates = [
+    import_node_path.default.resolve(cwd, configFile),
+    // ./env.meta.json (по умолчанию)
+    import_node_path.default.resolve(cwd, "examples", configFile),
+    // ./examples/env.meta.json
+    import_node_path.default.resolve(cwd, "examples", "env.meta.json")
+    // явный fallback
+  ];
+  const configPath = candidates.find((p) => import_node_fs.default.existsSync(p));
+  if (!configPath) {
+    console.error("\u274C env meta file not found.");
+    console.error("Tried:");
+    for (const p of candidates) console.error(`- ${p}`);
+    console.error("\nTip:");
+    console.error("  zod-envkit show -c examples/env.meta.json");
+    process.exit(1);
+  }
   const raw = import_node_fs.default.readFileSync(configPath, "utf8");
-  const meta = JSON.parse(raw);
+  return JSON.parse(raw);
+}
+var program = new import_commander.Command();
+program.name("zod-envkit").description("Env docs + runtime checks for Node.js projects");
+program.command("generate").description("Generate .env.example and ENV.md from env.meta.json").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md").action((opts) => {
+  const meta = loadMeta(opts.config);
   import_node_fs.default.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
   import_node_fs.default.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
   console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
 });
-program.parse();
+program.option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md");
+program.command("show").description("Show current env status (loads .env, masks secrets)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--env-file <file>", "Path to .env file", ".env").action((opts) => {
+  import_dotenv.default.config({ path: import_node_path.default.resolve(process.cwd(), opts.envFile), quiet: true });
+  const meta = loadMeta(opts.config);
+  const rows = Object.entries(meta).map(([key, m]) => {
+    const required = m.required === false ? "no" : "yes";
+    const raw = process.env[key];
+    const present = raw && raw.length > 0 ? "yes" : "no";
+    const value = raw ? maskValue(key, raw) : "";
+    return {
+      Key: key,
+      Required: required,
+      Present: present,
+      Value: value,
+      Description: m.description ?? ""
+    };
+  });
+  printTable(rows, ["Key", "Required", "Present", "Value", "Description"]);
+});
+program.command("check").description("Exit with code 1 if any required env var is missing (loads .env)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--env-file <file>", "Path to .env file", ".env").action((opts) => {
+  import_dotenv.default.config({ path: import_node_path.default.resolve(process.cwd(), opts.envFile) });
+  const meta = loadMeta(opts.config);
+  const missing = [];
+  for (const [key, m] of Object.entries(meta)) {
+    const required = m.required !== false;
+    if (!required) continue;
+    const raw = process.env[key];
+    if (!raw || raw.length === 0) missing.push(key);
+  }
+  if (missing.length) {
+    console.error("\u274C Missing required environment variables:");
+    for (const k of missing) console.error(`- ${k}`);
+    process.exit(1);
+  }
+  console.log("\u2705 Environment looks good.");
+});
+program.parse(process.argv);
+var hasSubcommand = process.argv.slice(2).some((a) => ["generate", "show", "check"].includes(a));
+if (!hasSubcommand) {
+  const opts = program.opts();
+  const meta = loadMeta(opts.config ?? "env.meta.json");
+  import_node_fs.default.writeFileSync(opts.outExample ?? ".env.example", generateEnvExample(meta), "utf8");
+  import_node_fs.default.writeFileSync(opts.outDocs ?? "ENV.md", generateEnvDocs(meta), "utf8");
+  console.log(`Generated: ${opts.outExample ?? ".env.example"}, ${opts.outDocs ?? "ENV.md"}`);
+}

package/dist/cli.js

@@ -4,6 +4,7 @@
 import fs from "fs";
 import path from "path";
 import { Command } from "commander";
+import dotenv from "dotenv";
 
 // src/generate.ts
 function strLen(s) {
@@ -75,13 +76,111 @@ function generateEnvDocs(meta) {
 }
 
 // src/cli.ts
-var program = new Command();
-program.name("zod-envkit").description("Generate .env.example and ENV.md from env.meta.json").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md").action((opts) => {
-  const configPath = path.resolve(process.cwd(), opts.config);
+function maskValue(key, value) {
+  const k = key.toUpperCase();
+  const isSecret = k.includes("TOKEN") || k.includes("SECRET") || k.includes("PASSWORD") || k.includes("API_KEY") || k.includes("KEY");
+  if (!isSecret) return value;
+  if (value.length <= 4) return "*".repeat(value.length);
+  return value.slice(0, 2) + "*".repeat(Math.max(1, value.length - 4)) + value.slice(-2);
+}
+function padCenter2(text, width) {
+  const t = text ?? "";
+  const diff = width - t.length;
+  if (diff <= 0) return t;
+  const left = Math.floor(diff / 2);
+  const right = diff - left;
+  return " ".repeat(left) + t + " ".repeat(right);
+}
+function printTable(rows, headers) {
+  const widths = {};
+  for (const h of headers) widths[h] = h.length;
+  for (const row of rows) {
+    for (const h of headers) {
+      widths[h] = Math.max(widths[h], (row[h] ?? "").length);
+    }
+  }
+  for (const h of headers) widths[h] += 2;
+  const line = "|" + headers.map((h) => " " + padCenter2(h, widths[h]) + " ").join("|") + "|";
+  const sep = "|" + headers.map((h) => ":" + "-".repeat(Math.max(3, widths[h])) + ":").join("|") + "|";
+  console.log(line);
+  console.log(sep);
+  for (const row of rows) {
+    const rowLine = "|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|";
+    console.log(rowLine);
+  }
+}
+function loadMeta(configFile) {
+  const cwd = process.cwd();
+  const candidates = [
+    path.resolve(cwd, configFile),
+    // ./env.meta.json (по умолчанию)
+    path.resolve(cwd, "examples", configFile),
+    // ./examples/env.meta.json
+    path.resolve(cwd, "examples", "env.meta.json")
+    // явный fallback
+  ];
+  const configPath = candidates.find((p) => fs.existsSync(p));
+  if (!configPath) {
+    console.error("\u274C env meta file not found.");
+    console.error("Tried:");
+    for (const p of candidates) console.error(`- ${p}`);
+    console.error("\nTip:");
+    console.error("  zod-envkit show -c examples/env.meta.json");
+    process.exit(1);
+  }
   const raw = fs.readFileSync(configPath, "utf8");
-  const meta = JSON.parse(raw);
+  return JSON.parse(raw);
+}
+var program = new Command();
+program.name("zod-envkit").description("Env docs + runtime checks for Node.js projects");
+program.command("generate").description("Generate .env.example and ENV.md from env.meta.json").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md").action((opts) => {
+  const meta = loadMeta(opts.config);
   fs.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
   fs.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
   console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
 });
-program.parse();
+program.option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md");
+program.command("show").description("Show current env status (loads .env, masks secrets)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--env-file <file>", "Path to .env file", ".env").action((opts) => {
+  dotenv.config({ path: path.resolve(process.cwd(), opts.envFile), quiet: true });
+  const meta = loadMeta(opts.config);
+  const rows = Object.entries(meta).map(([key, m]) => {
+    const required = m.required === false ? "no" : "yes";
+    const raw = process.env[key];
+    const present = raw && raw.length > 0 ? "yes" : "no";
+    const value = raw ? maskValue(key, raw) : "";
+    return {
+      Key: key,
+      Required: required,
+      Present: present,
+      Value: value,
+      Description: m.description ?? ""
+    };
+  });
+  printTable(rows, ["Key", "Required", "Present", "Value", "Description"]);
+});
+program.command("check").description("Exit with code 1 if any required env var is missing (loads .env)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--env-file <file>", "Path to .env file", ".env").action((opts) => {
+  dotenv.config({ path: path.resolve(process.cwd(), opts.envFile) });
+  const meta = loadMeta(opts.config);
+  const missing = [];
+  for (const [key, m] of Object.entries(meta)) {
+    const required = m.required !== false;
+    if (!required) continue;
+    const raw = process.env[key];
+    if (!raw || raw.length === 0) missing.push(key);
+  }
+  if (missing.length) {
+    console.error("\u274C Missing required environment variables:");
+    for (const k of missing) console.error(`- ${k}`);
+    process.exit(1);
+  }
+  console.log("\u2705 Environment looks good.");
+});
+program.parse(process.argv);
+var hasSubcommand = process.argv.slice(2).some((a) => ["generate", "show", "check"].includes(a));
+if (!hasSubcommand) {
+  const opts = program.opts();
+  const meta = loadMeta(opts.config ?? "env.meta.json");
+  fs.writeFileSync(opts.outExample ?? ".env.example", generateEnvExample(meta), "utf8");
+  fs.writeFileSync(opts.outDocs ?? "ENV.md", generateEnvDocs(meta), "utf8");
+  console.log(`Generated: ${opts.outExample ?? ".env.example"}, ${opts.outDocs ?? "ENV.md"}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-envkit",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Validate environment variables with Zod and generate .env.example",
   "type": "module",
   "main": "dist/index.cjs",