zod-envkit 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] – 2026-01-26
+
+### Added
+- Initial release of **zod-envkit**
+- Type-safe environment variable validation using Zod
+- `loadEnv` helper for safe runtime parsing of `process.env`
+- `formatZodError` for human-readable error output
+- 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
+- Explicit configuration over magic
+- No automatic schema introspection for documentation generation
+- 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nxtxe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,28 @@
-Type-safe environment variable validation and documentation using Zod.
-
-`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
+<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>
+</div>
+
+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.
+
+- 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.
 
@@ -13,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
 
 ---
 
@@ -42,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";
@@ -52,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);
@@ -70,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`.
+
+By default, it is searched in:
 
-### 1️⃣ Create `env.meta.json` in your project root
+* `./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
 ```
 
 ---
@@ -161,6 +197,7 @@ zod-envkit \
 * ❌ no validation
 * ❌ no types
 * ❌ no documentation
+* ❌ no CI checks
 
 `zod-envkit`:
 
@@ -169,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,13 +1,11 @@
 {
   "name": "zod-envkit",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Validate environment variables with Zod and generate .env.example",
   "type": "module",
-
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,28 +13,43 @@
       "require": "./dist/index.cjs"
     }
   },
-
   "bin": {
     "zod-envkit": "dist/cli.js"
   },
-
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxtxe/zod-envkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nxtxe/zod-envkit/issues"
+  },
+  "homepage": "https://github.com/nxtxe/zod-envkit#readme",
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts --format esm,cjs --dts",
     "dev": "tsup src/index.ts src/cli.ts --watch --dts",
     "test": "vitest run",
     "prepublishOnly": "npm run test && npm run build"
   },
-
-  "keywords": ["env", "dotenv", "zod", "validation", "cli"],
+  "keywords": [
+    "env",
+    "dotenv",
+    "zod",
+    "validation",
+    "cli"
+  ],
   "author": "",
   "license": "MIT",
-
   "dependencies": {
     "commander": "^13.1.0",
     "dotenv": "^17.2.3",
     "zod": "^4.3.6"
   },
-
   "devDependencies": {
     "@types/node": "^25.0.10",
     "eslint": "^9.39.2",

package/.env.example

@@ -1,8 +0,0 @@
-# Runtime mode
-NODE_ENV=development
-
-# HTTP port
-PORT=3000
-
-# Postgres connection string
-DATABASE_URL=postgresql://user:pass@localhost:5432/db

package/ENV.md

@@ -1,7 +0,0 @@
-# Environment variables
-
-|      Key       |  Required  |                  Example                   |         Description          |
-| :------------: | :--------: | :----------------------------------------: | :--------------------------: |
-|    NODE_ENV    |    yes     |                development                 |         Runtime mode         |
-|      PORT      |    yes     |                    3000                    |          HTTP port           |
-|  DATABASE_URL  |    yes     |  postgresql://user:pass@localhost:5432/db  |  Postgres connection string  |

package/env.meta.json

@@ -1,5 +0,0 @@
-{
-  "NODE_ENV": { "description": "Runtime mode", "example": "development" },
-  "PORT": { "description": "HTTP port", "example": "3000" },
-  "DATABASE_URL": { "description": "Postgres connection string", "example": "postgresql://user:pass@localhost:5432/db" }
-}

package/src/cli.ts

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import { Command } from "commander";
-import { generateEnvDocs, generateEnvExample, type EnvMeta } from "./generate.js";
-
-const 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);
-    const raw = fs.readFileSync(configPath, "utf8");
-    const meta: EnvMeta = JSON.parse(raw);
-
-    fs.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
-    fs.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
-
-    console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
-  });
-
-program.parse();

package/src/generate.ts

@@ -1,130 +0,0 @@
-// src/generate.ts
-
-export type EnvMeta = Record<
-  string,
-  {
-    description?: string;
-    example?: string;
-    required?: boolean; // default: true
-  }
->;
-
-function strLen(s: string): number {
-  return s.length;
-}
-
-function padCenter(text: string, width: number): string {
-  const t = text ?? "";
-  const diff = width - strLen(t);
-  if (diff <= 0) return t;
-
-  const left = Math.floor(diff / 2);
-  const right = diff - left;
-  return " ".repeat(left) + t + " ".repeat(right);
-}
-
-function padRight(text: string, width: number): string {
-  const t = text ?? "";
-  const diff = width - strLen(t);
-  if (diff <= 0) return t;
-  return t + " ".repeat(diff);
-}
-
-function makeDivider(width: number, align: "left" | "center" | "right"): string {
-  // Markdown alignment:
-  // left   : --- 
-  // center : :---:
-  // right  : ---:
-  if (width < 3) width = 3;
-
-  if (align === "center") return ":" + "-".repeat(width - 2) + ":";
-  if (align === "right") return "-".repeat(width - 1) + ":";
-  return "-".repeat(width);
-}
-
-/**
- * Генерит .env.example красиво:
- * - комментарий с description
- * - KEY=example
- */
-export function generateEnvExample(meta: EnvMeta): string {
-  const lines: string[] = [];
-
-  for (const [key, m] of Object.entries(meta)) {
-    if (m.description) lines.push(`# ${m.description}`);
-    lines.push(`${key}=${m.example ?? ""}`);
-    lines.push("");
-  }
-
-  return lines.join("\n").trim() + "\n";
-}
-
-/**
- * Генерит ENV.md как ровную таблицу:
- * - вычисляет ширины колонок по максимальной длине
- * - паддит значения пробелами
- * - ставит выравнивание :---: чтобы центрировалось в Markdown
- */
-export function generateEnvDocs(meta: EnvMeta): string {
-  const headers = ["Key", "Required", "Example", "Description"] as const;
-
-  const rows = Object.entries(meta).map(([key, m]) => {
-    const req = m.required === false ? "no" : "yes";
-    return {
-      Key: key,
-      Required: req,
-      Example: m.example ?? "",
-      Description: m.description ?? "",
-    };
-  });
-
-  const widths = {
-    Key: headers[0].length,
-    Required: headers[1].length,
-    Example: headers[2].length,
-    Description: headers[3].length,
-  };
-
-  for (const r of rows) {
-    widths.Key = Math.max(widths.Key, strLen(r.Key));
-    widths.Required = Math.max(widths.Required, strLen(r.Required));
-    widths.Example = Math.max(widths.Example, strLen(r.Example));
-    widths.Description = Math.max(widths.Description, strLen(r.Description));
-  }
-
-  widths.Key += 2;
-  widths.Required += 2;
-  widths.Example += 2;
-  widths.Description += 2;
-
-  const headerLine =
-    `| ${padCenter(headers[0], widths.Key)} ` +
-    `| ${padCenter(headers[1], widths.Required)} ` +
-    `| ${padCenter(headers[2], widths.Example)} ` +
-    `| ${padCenter(headers[3], widths.Description)} |`;
-
-  const dividerLine =
-    `| ${makeDivider(widths.Key, "center")} ` +
-    `| ${makeDivider(widths.Required, "center")} ` +
-    `| ${makeDivider(widths.Example, "center")} ` +
-    `| ${makeDivider(widths.Description, "center")} |`;
-
-  const bodyLines = rows.map((r) => {
-    return (
-      `| ${padCenter(r.Key, widths.Key)} ` +
-      `| ${padCenter(r.Required, widths.Required)} ` +
-      `| ${padCenter(r.Example, widths.Example)} ` +
-      `| ${padCenter(r.Description, widths.Description)} |`
-    );
-  });
-
-
-  return [
-    `# Environment variables`,
-    ``,
-    headerLine,
-    dividerLine,
-    ...bodyLines,
-    ``,
-  ].join("\n");
-}

package/src/index.ts

@@ -1,23 +0,0 @@
-import { z } from "zod";
-
-export type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
-
-export function loadEnv<T extends z.ZodTypeAny>(
-  schema: T,
-  opts?: { throwOnError?: boolean }
-):
-  | { ok: true; env: z.infer<T> }
-  | { ok: false; error: z.ZodError } {
-  const parsed = schema.safeParse(process.env);
-
-  if (parsed.success) return { ok: true, env: parsed.data };
-
-  if (opts?.throwOnError) throw parsed.error;
-  return { ok: false, error: parsed.error };
-}
-
-export function formatZodError(err: z.ZodError): string {
-  return err.issues
-    .map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`)
-    .join("\n");
-}

package/test/basic.test.ts

@@ -1,15 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { z } from "zod";
-import { loadEnv } from "../src/index";
-
-describe("loadEnv", () => {
-  it("parses valid env", () => {
-    process.env.PORT = "3000";
-    const schema = z.object({ PORT: z.coerce.number() });
-
-    const res = loadEnv(schema);
-    expect(res.ok).toBe(true);
-
-    if (res.ok) expect(res.env.PORT).toBe(3000);
-  });
-});

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "declaration": true,
-    "skipLibCheck": true
-  }
-}