zod-envkit 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## [1.0.5](https://github.com/nxtxe/zod-envkit/compare/v1.0.4...v1.0.5) (2026-01-26)
+
+
+### Bug Fixes
+
+* release 1.0.5 ([4d48479](https://github.com/nxtxe/zod-envkit/commit/4d48479b62819d4c17cc05eb14c64f387806cbec))
+
+## [1.0.4](https://github.com/nxtxe/zod-envkit/compare/v1.0.3...v1.0.4) (2026-01-26)
+
+
+### Bug Fixes
+
+* **ci:** retry install to avoid rollup optional deps issue ([356e2c2](https://github.com/nxtxe/zod-envkit/commit/356e2c2b8980484767be29062d5f8eb4cdb4fde4))
+* **ci:** retry install to avoid rollup optional deps issue ([7063e29](https://github.com/nxtxe/zod-envkit/commit/7063e29bb5cc3c7a8151a2afade035300ac5cff0))
+* **cli:** stabilize release and execution behavior ([13f9b4f](https://github.com/nxtxe/zod-envkit/commit/13f9b4fe9f8893ec0d0b5b0f2373ef24cad76108))
+* **release:** publish fix ([6811915](https://github.com/nxtxe/zod-envkit/commit/681191593e681d48b2e6490fcdd49f2b06a6bda5))
+* **release:** publish repair ([a7f6557](https://github.com/nxtxe/zod-envkit/commit/a7f655758b3c214bb977f1e34cbb10246b39234a))
+* **release:** publish retry ([1c55df0](https://github.com/nxtxe/zod-envkit/commit/1c55df00cf48623178d0a7cc81dfc68fc7b8dac0))
+* **release:** retry with granular npm token ([c851824](https://github.com/nxtxe/zod-envkit/commit/c851824ba1777d31e14f7ea5306dc92adcab4de7))
+* trigger patch release ([2c978e5](https://github.com/nxtxe/zod-envkit/commit/2c978e5b93b159117ca52eeed84e07063e9ecfea))
+
+## [1.0.4](https://github.com/nxtxe/zod-envkit/compare/v1.0.3...v1.0.4) (2026-01-26)
+
+
+### Bug Fixes
+
+* **ci:** retry install to avoid rollup optional deps issue ([356e2c2](https://github.com/nxtxe/zod-envkit/commit/356e2c2b8980484767be29062d5f8eb4cdb4fde4))
+* **ci:** retry install to avoid rollup optional deps issue ([7063e29](https://github.com/nxtxe/zod-envkit/commit/7063e29bb5cc3c7a8151a2afade035300ac5cff0))
+* **cli:** stabilize release and execution behavior ([13f9b4f](https://github.com/nxtxe/zod-envkit/commit/13f9b4fe9f8893ec0d0b5b0f2373ef24cad76108))
+* **release:** publish fix ([6811915](https://github.com/nxtxe/zod-envkit/commit/681191593e681d48b2e6490fcdd49f2b06a6bda5))
+* **release:** publish repair ([a7f6557](https://github.com/nxtxe/zod-envkit/commit/a7f655758b3c214bb977f1e34cbb10246b39234a))
+* **release:** publish retry ([1c55df0](https://github.com/nxtxe/zod-envkit/commit/1c55df00cf48623178d0a7cc81dfc68fc7b8dac0))
+* **release:** retry with granular npm token ([c851824](https://github.com/nxtxe/zod-envkit/commit/c851824ba1777d31e14f7ea5306dc92adcab4de7))
+
 # Changelog
 
 All notable changes to this project will be documented in this file.  
@@ -5,17 +39,54 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [1.0.2] – 2026-01-26
+## [1.0.5] – 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
+- `mustLoadEnv` helper for fail-fast env loading (throws on invalid env)
+- Default CLI behavior: running `zod-envkit` without subcommand now behaves like `zod-envkit generate`
+- Better secret masking in `zod-envkit show` (TOKEN / SECRET / PASSWORD / *_KEY / PRIVATE)
+
+### Changed
+- Public API (`loadEnv`, `mustLoadEnv`, `formatZodError`) stabilized and separated from CLI/generators
+- CLI error handling improved:
+  - no stack traces for user errors
+  - consistent human-readable messages
+  - strict exit codes (`0` success, `1` error)
+- `ENV.md` generation now produces fully centered, width-aware Markdown tables
+- CLI now reliably resolves `env.meta.json` from:
+  - project root
+  - `./examples/`
+  - explicit `-c/--config` path
+
+### Fixed
+- TypeScript type narrowing issues in CLI (`fs.readFileSync` with undefined paths)
+- Potential double execution when running CLI without subcommands
+- Inconsistent env loading behavior across CLI commands
+
+[1.0.5]: https://www.npmjs.com/package/zod-envkit/v/1.0.5
+
+---
+
+## [1.0.4] – 2026-01-26
+
+### Added
+- `zod-envkit show` command to display env status in a readable table (with secret masking)
+- `zod-envkit check` command to validate required variables (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.4]: https://www.npmjs.com/package/zod-envkit/v/1.0.4
+
+---
+
+## [1.0.3] – 2026-01-26
+- Git tag only (not published to npm)
+
+---
+
+## [1.0.2] – 2026-01-26
+- Git tag only (not published to npm)
 
 ---
 

package/README.RU.md

@@ -0,0 +1,278 @@
+<div align="center">
+  <br />
+  <p>
+    <img src="./zod-envkit.svg" width="546" alt="zod-envkit" />
+  </p>
+  <br />
+  <p>
+    <a href="https://github.com/nxtxe/zod-envkit">
+      <img src="https://github.com/nxtxe/zod-envkit/actions/workflows/release.yml/badge.svg" />
+    </a>
+    <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>
+    <a href="./README.md">English</a> |
+    <a href="./README.RU.md">Русский</a>
+  </p>
+</div>
+
+Ниже — русский перевод текста, сохраняя структуру и смысл оригинала.
+
+---
+
+Типобезопасная валидация и документация переменных окружения с помощью **Zod**.
+
+**zod-envkit** — это небольшая библиотека + CLI, которая помогает воспринимать переменные окружения как
+**явный контракт времени выполнения**, а не как игру в угадайку.
+
+* валидация `process.env` при старте приложения
+* полностью типизированные переменные окружения
+* генерация `.env.example`
+* генерация читаемой документации (`ENV.md`)
+* просмотр и проверка состояния env через CLI
+* быстрый фейл в CI/CD до деплоя
+
+Никакого облака. Никакой магии. Только код.
+
+---
+
+## Зачем
+
+Переменные окружения критичны, но почти всегда обрабатываются плохо.
+
+Типичные проблемы:
+
+* `process.env` — это просто `string | undefined`
+* отсутствующие или некорректные переменные падают **во время выполнения**
+* `.env.example` и документация быстро устаревают
+* CI/CD ломается поздно и непредсказуемо
+
+**zod-envkit** решает это, делая env:
+
+* валидируемым на раннем этапе
+* типизированным
+* документированным
+* проверяемым в CI
+
+---
+
+## Установка
+
+```bash
+npm install zod-envkit
+```
+
+```bash
+yarn add zod-envkit
+```
+
+```bash
+pnpm add zod-envkit
+```
+
+---
+
+## Использование библиотеки (runtime-валидация)
+
+Создайте один файл, отвечающий за загрузку и валидацию env.
+
+```ts
+import "dotenv/config";
+import { z } from "zod";
+import { loadEnv, mustLoadEnv, 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(),
+});
+```
+
+### Вариант 1 — безопасный режим (без исключений)
+
+```ts
+const result = loadEnv(EnvSchema);
+
+if (!result.ok) {
+  console.error("Некорректное окружение:\n" + formatZodError(result.error));
+  process.exit(1);
+}
+
+export const env = result.env;
+```
+
+### Вариант 2 — fail-fast (рекомендуется)
+
+```ts
+export const env = mustLoadEnv(EnvSchema);
+```
+
+Теперь:
+
+* `env.PORT` — это **number**
+* `env.DATABASE_URL` — это **string**
+* TypeScript всё знает на этапе компиляции
+* приложение падает сразу, если env некорректен
+
+---
+
+## Использование CLI
+
+CLI работает на основе простого мета-файла: `env.meta.json`.
+
+По умолчанию он ищется в:
+
+* `./env.meta.json`
+* `./examples/env.meta.json`
+
+---
+
+### Пример `env.meta.json`
+
+```json
+{
+  "NODE_ENV": {
+    "description": "Режим выполнения",
+    "example": "development",
+    "required": true
+  },
+  "PORT": {
+    "description": "HTTP-порт",
+    "example": "3000",
+    "required": true
+  },
+  "DATABASE_URL": {
+    "description": "Строка подключения к Postgres",
+    "example": "postgresql://user:pass@localhost:5432/db",
+    "required": true
+  }
+}
+```
+
+---
+
+## Команды CLI
+
+### Генерация `.env.example` и `ENV.md`
+
+(Поведение по умолчанию)
+
+```bash
+npx zod-envkit
+```
+
+или явно:
+
+```bash
+npx zod-envkit generate
+```
+
+---
+
+### Просмотр текущего состояния окружения
+
+Загружает `.env`, маскирует секреты и показывает читаемую таблицу.
+
+```bash
+npx zod-envkit show
+```
+
+Показывает:
+
+* какие переменные обязательны
+* какие присутствуют
+* замаскированные значения секретов (`TOKEN`, `SECRET`, `*_KEY` и т.д.)
+
+---
+
+### Проверка обязательных переменных (удобно для CI)
+
+```bash
+npx zod-envkit check
+```
+
+* завершает процесс с кодом `1`, если отсутствует хотя бы одна обязательная переменная
+* идеально для CI/CD пайплайнов и pre-deploy проверок
+
+Пример шага в CI:
+
+```bash
+npx zod-envkit check
+```
+
+---
+
+### Опции CLI
+
+```bash
+zod-envkit --help
+```
+
+Часто используемые флаги:
+
+```bash
+zod-envkit show \
+  --config examples/env.meta.json \
+  --env-file .env
+```
+
+---
+
+## Почему не просто dotenv?
+
+`dotenv`:
+
+* ❌ нет валидации
+* ❌ нет типов
+* ❌ нет документации
+* ❌ нет проверок для CI
+
+`zod-envkit`:
+
+* ✅ валидация
+* ✅ вывод типов для TypeScript
+* ✅ документация
+* ✅ CLI-инструменты
+
+Они созданы для использования **вместе**.
+
+---
+
+## Принципы дизайна
+
+* явная конфигурация вместо магии
+* отсутствие привязки к фреймворкам
+* маленький и предсказуемый API
+* библиотека и CLI независимы, но дополняют друг друга
+* переменные окружения — это runtime-контракт
+
+---
+
+## Roadmap
+
+* [ ] проверка согласованности schema ↔ meta
+* [ ] группировка секций в сгенерированной документации
+* [ ] более аккуратный и человеко-понятный вывод ошибок
+* [ ] экспорт в JSON Schema
+* [ ] более строгие режимы валидации для production
+
+---
+
+## Для кого это?
+
+* backend- и fullstack-проекты
+* сервисы на Node.js и Bun
+* CI/CD пайплайны
+* команды, которые хотят, чтобы ошибки env находились рано, а не поздно
+
+---
+
+## Лицензия
+
+MIT

package/README.md

@@ -5,6 +5,9 @@
   </p>
   <br />
   <p>
+    <a href="https://github.com/nxtxe/zod-envkit">
+      <img src="https://github.com/nxtxe/zod-envkit/actions/workflows/release.yml/badge.svg" />
+    </a>
     <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>
@@ -12,17 +15,25 @@
       <img src="https://img.shields.io/npm/dt/zod-envkit.svg?maxAge=100" alt="npm downloads" />
     </a>
   </p>
+
+ <p>
+  <a href="./README.md">English</a> |
+  <a href="./README.RU.md">Русский</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.
+**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
+- fail fast in CI/CD before deploy
 
 No cloud. No magic. Just code.
 
@@ -32,7 +43,7 @@ No cloud. No magic. Just code.
 
 Environment variables are critical, but usually poorly handled.
 
-The usual problems:
+Typical problems:
 - `process.env` is just `string | undefined`
 - missing or invalid variables fail **at runtime**
 - `.env.example` and docs get outdated
@@ -52,7 +63,9 @@ The usual problems:
 npm install zod-envkit
 ````
 
-or
+```bash
+yarn add zod-envkit
+```
 
 ```bash
 pnpm add zod-envkit
@@ -67,14 +80,18 @@ Create a single file responsible for loading and validating env.
 ```ts
 import "dotenv/config";
 import { z } from "zod";
-import { loadEnv, formatZodError } from "zod-envkit";
+import { loadEnv, mustLoadEnv, 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(),
 });
+```
+
+### Option 1 — safe mode (no throw)
 
+```ts
 const result = loadEnv(EnvSchema);
 
 if (!result.ok) {
@@ -85,6 +102,12 @@ if (!result.ok) {
 export const env = result.env;
 ```
 
+### Option 2 — fail-fast (recommended)
+
+```ts
+export const env = mustLoadEnv(EnvSchema);
+```
+
 Now:
 
 * `env.PORT` is a **number**
@@ -155,11 +178,11 @@ Loads `.env`, masks secrets, and displays a readable table.
 npx zod-envkit show
 ```
 
-Example output:
+Shows:
 
 * which variables are required
 * which are present
-* masked values for secrets
+* masked values for secrets (`TOKEN`, `SECRET`, `*_KEY`, etc.)
 
 ---
 
@@ -170,7 +193,13 @@ npx zod-envkit check
 ```
 
 * exits with code `1` if any required variable is missing
-* perfect for CI/CD pipelines and pre-deploy checks
+* ideal for CI/CD pipelines and pre-deploy checks
+
+Example CI step:
+
+```bash
+npx zod-envkit check
+```
 
 ---
 
@@ -242,4 +271,3 @@ They are designed to be used **together**.
 ## License
 
 MIT
-

package/dist/cli.cjs

@@ -29,17 +29,56 @@ var import_node_path = __toESM(require("path"), 1);
 var import_commander = require("commander");
 var import_dotenv = __toESM(require("dotenv"), 1);
 
+// src/messages.ts
+var messages = {
+  en: {
+    META_NOT_FOUND: "env meta file not found.",
+    META_TRIED: "Tried:",
+    META_TIP: "Tip:",
+    GENERATED: "Generated: {example}, {docs}",
+    ENV_OK: "Environment looks good.",
+    MISSING_ENV: "Missing required environment variables:",
+    META_PARSE_FAILED: "Failed to read/parse env meta file:"
+  },
+  ru: {
+    META_NOT_FOUND: "\u0424\u0430\u0439\u043B env.meta.json \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D.",
+    META_TRIED: "\u041F\u0440\u043E\u0431\u043E\u0432\u0430\u043B\u0438:",
+    META_TIP: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430:",
+    GENERATED: "\u0421\u0433\u0435\u043D\u0435\u0440\u0438\u0440\u043E\u0432\u0430\u043D\u043E: {example}, {docs}",
+    ENV_OK: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u0432 \u043F\u043E\u0440\u044F\u0434\u043A\u0435.",
+    MISSING_ENV: "\u041E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u044E\u0442 \u043E\u0431\u044F\u0437\u0430\u0442\u0435\u043B\u044C\u043D\u044B\u0435 \u043F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F:",
+    META_PARSE_FAILED: "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u043F\u0440\u043E\u0447\u0438\u0442\u0430\u0442\u044C/\u0440\u0430\u0441\u043F\u0430\u0440\u0441\u0438\u0442\u044C env meta \u0444\u0430\u0439\u043B:"
+  }
+};
+
+// src/i18n.ts
+function resolveLang(cliLang) {
+  if (cliLang === "ru" || cliLang === "en") return cliLang;
+  const envLang = process.env.LANG?.toLowerCase();
+  if (envLang?.startsWith("ru")) return "ru";
+  return "en";
+}
+function t(lang, key, vars) {
+  let text = messages[lang][key] ?? messages.en[key];
+  if (vars) {
+    for (const [k, v] of Object.entries(vars)) {
+      text = text.replace(`{${k}}`, v);
+    }
+  }
+  return text;
+}
+
 // src/generate.ts
 function strLen(s) {
-  return s.length;
+  return (s ?? "").length;
 }
 function padCenter(text, width) {
-  const t = text ?? "";
-  const diff = width - strLen(t);
-  if (diff <= 0) return t;
+  const t2 = text ?? "";
+  const diff = width - strLen(t2);
+  if (diff <= 0) return t2;
   const left = Math.floor(diff / 2);
   const right = diff - left;
-  return " ".repeat(left) + t + " ".repeat(right);
+  return " ".repeat(left) + t2 + " ".repeat(right);
 }
 function makeDivider(width, align) {
   if (width < 3) width = 3;
@@ -54,7 +93,7 @@ function generateEnvExample(meta) {
     lines.push(`${key}=${m.example ?? ""}`);
     lines.push("");
   }
-  return lines.join("\n").trim() + "\n";
+  return lines.join("\n").trimEnd() + "\n";
 }
 function generateEnvDocs(meta) {
   const headers = ["Key", "Required", "Example", "Description"];
@@ -99,73 +138,83 @@ function generateEnvDocs(meta) {
 }
 
 // src/cli.ts
+function fail(lang, key, details) {
+  console.error(`\u274C ${t(lang, key)}`);
+  if (details?.length) for (const d of details) console.error(d);
+  process.exit(1);
+}
 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");
+  const isSecret = k.includes("TOKEN") || k.includes("SECRET") || k.includes("PASSWORD") || k.includes("API_KEY") || k.endsWith("_KEY") || k.includes("PRIVATE");
   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 v = text ?? "";
+  const diff = width - v.length;
+  if (diff <= 0) return v;
   const left = Math.floor(diff / 2);
   const right = diff - left;
-  return " ".repeat(left) + t + " ".repeat(right);
+  return " ".repeat(left) + v + " ".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] = 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);
+  const headerLine = "|" + headers.map((h) => " " + padCenter2(h, widths[h]) + " ").join("|") + "|";
+  const sepLine = "|" + headers.map((h) => ":" + "-".repeat(Math.max(3, widths[h])) + ":").join("|") + "|";
+  console.log(headerLine);
+  console.log(sepLine);
   for (const row of rows) {
-    const rowLine = "|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|";
-    console.log(rowLine);
+    console.log("|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|");
   }
 }
-function loadMeta(configFile) {
+function loadDotEnv(envFile) {
+  import_dotenv.default.config({ path: import_node_path.default.resolve(process.cwd(), envFile), quiet: true });
+}
+function loadMeta(lang, 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 found = candidates.find((p) => import_node_fs.default.existsSync(p));
+  if (!found) {
+    fail(lang, "META_NOT_FOUND", [
+      t(lang, "META_TRIED"),
+      ...candidates.map((p) => `- ${p}`),
+      "",
+      t(lang, "META_TIP"),
+      "  npx zod-envkit show -c examples/env.meta.json"
+    ]);
+  }
+  const configPath = found;
+  try {
+    const raw = import_node_fs.default.readFileSync(configPath, "utf8");
+    return { meta: JSON.parse(raw), configPath };
+  } catch {
+    fail(lang, "META_PARSE_FAILED", [`- ${configPath}`]);
   }
-  const raw = import_node_fs.default.readFileSync(configPath, "utf8");
-  return JSON.parse(raw);
 }
 var program = new import_commander.Command();
-program.name("zod-envkit").description("Env docs + runtime checks for Node.js projects");
+program.name("zod-envkit").description("Env docs + runtime checks for Node.js projects").showHelpAfterError().showSuggestionAfterError().option("--lang <lang>", "CLI language (en | ru)");
 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);
+  const lang = resolveLang(program.opts().lang);
+  const { meta } = loadMeta(lang, 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}`);
+  console.log(t(lang, "GENERATED", { example: opts.outExample, docs: opts.outDocs }));
+  process.exit(0);
 });
-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 lang = resolveLang(program.opts().lang);
+  loadDotEnv(opts.envFile);
+  const { meta } = loadMeta(lang, opts.config);
   const rows = Object.entries(meta).map(([key, m]) => {
     const required = m.required === false ? "no" : "yes";
     const raw = process.env[key];
@@ -180,10 +229,12 @@ program.command("show").description("Show current env status (loads .env, masks
     };
   });
   printTable(rows, ["Key", "Required", "Present", "Value", "Description"]);
+  process.exit(0);
 });
 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 lang = resolveLang(program.opts().lang);
+  loadDotEnv(opts.envFile);
+  const { meta } = loadMeta(lang, opts.config);
   const missing = [];
   for (const [key, m] of Object.entries(meta)) {
     const required = m.required !== false;
@@ -192,18 +243,14 @@ program.command("check").description("Exit with code 1 if any required env var i
     if (!raw || raw.length === 0) missing.push(key);
   }
   if (missing.length) {
-    console.error("\u274C Missing required environment variables:");
+    console.error(`\u274C ${t(lang, "MISSING_ENV")}`);
     for (const k of missing) console.error(`- ${k}`);
     process.exit(1);
   }
-  console.log("\u2705 Environment looks good.");
+  console.log(`\u2705 ${t(lang, "ENV_OK")}`);
+  process.exit(0);
 });
+var known = /* @__PURE__ */ new Set(["generate", "show", "check", "-h", "--help", "-V", "--version", "--lang"]);
+var hasCommand = process.argv.slice(2).some((a) => known.has(a));
+if (!hasCommand) process.argv.splice(2, 0, "generate");
 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

@@ -6,17 +6,56 @@ import path from "path";
 import { Command } from "commander";
 import dotenv from "dotenv";
 
+// src/messages.ts
+var messages = {
+  en: {
+    META_NOT_FOUND: "env meta file not found.",
+    META_TRIED: "Tried:",
+    META_TIP: "Tip:",
+    GENERATED: "Generated: {example}, {docs}",
+    ENV_OK: "Environment looks good.",
+    MISSING_ENV: "Missing required environment variables:",
+    META_PARSE_FAILED: "Failed to read/parse env meta file:"
+  },
+  ru: {
+    META_NOT_FOUND: "\u0424\u0430\u0439\u043B env.meta.json \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D.",
+    META_TRIED: "\u041F\u0440\u043E\u0431\u043E\u0432\u0430\u043B\u0438:",
+    META_TIP: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430:",
+    GENERATED: "\u0421\u0433\u0435\u043D\u0435\u0440\u0438\u0440\u043E\u0432\u0430\u043D\u043E: {example}, {docs}",
+    ENV_OK: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u0432 \u043F\u043E\u0440\u044F\u0434\u043A\u0435.",
+    MISSING_ENV: "\u041E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u044E\u0442 \u043E\u0431\u044F\u0437\u0430\u0442\u0435\u043B\u044C\u043D\u044B\u0435 \u043F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F:",
+    META_PARSE_FAILED: "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u043F\u0440\u043E\u0447\u0438\u0442\u0430\u0442\u044C/\u0440\u0430\u0441\u043F\u0430\u0440\u0441\u0438\u0442\u044C env meta \u0444\u0430\u0439\u043B:"
+  }
+};
+
+// src/i18n.ts
+function resolveLang(cliLang) {
+  if (cliLang === "ru" || cliLang === "en") return cliLang;
+  const envLang = process.env.LANG?.toLowerCase();
+  if (envLang?.startsWith("ru")) return "ru";
+  return "en";
+}
+function t(lang, key, vars) {
+  let text = messages[lang][key] ?? messages.en[key];
+  if (vars) {
+    for (const [k, v] of Object.entries(vars)) {
+      text = text.replace(`{${k}}`, v);
+    }
+  }
+  return text;
+}
+
 // src/generate.ts
 function strLen(s) {
-  return s.length;
+  return (s ?? "").length;
 }
 function padCenter(text, width) {
-  const t = text ?? "";
-  const diff = width - strLen(t);
-  if (diff <= 0) return t;
+  const t2 = text ?? "";
+  const diff = width - strLen(t2);
+  if (diff <= 0) return t2;
   const left = Math.floor(diff / 2);
   const right = diff - left;
-  return " ".repeat(left) + t + " ".repeat(right);
+  return " ".repeat(left) + t2 + " ".repeat(right);
 }
 function makeDivider(width, align) {
   if (width < 3) width = 3;
@@ -31,7 +70,7 @@ function generateEnvExample(meta) {
     lines.push(`${key}=${m.example ?? ""}`);
     lines.push("");
   }
-  return lines.join("\n").trim() + "\n";
+  return lines.join("\n").trimEnd() + "\n";
 }
 function generateEnvDocs(meta) {
   const headers = ["Key", "Required", "Example", "Description"];
@@ -76,73 +115,83 @@ function generateEnvDocs(meta) {
 }
 
 // src/cli.ts
+function fail(lang, key, details) {
+  console.error(`\u274C ${t(lang, key)}`);
+  if (details?.length) for (const d of details) console.error(d);
+  process.exit(1);
+}
 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");
+  const isSecret = k.includes("TOKEN") || k.includes("SECRET") || k.includes("PASSWORD") || k.includes("API_KEY") || k.endsWith("_KEY") || k.includes("PRIVATE");
   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 v = text ?? "";
+  const diff = width - v.length;
+  if (diff <= 0) return v;
   const left = Math.floor(diff / 2);
   const right = diff - left;
-  return " ".repeat(left) + t + " ".repeat(right);
+  return " ".repeat(left) + v + " ".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] = 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);
+  const headerLine = "|" + headers.map((h) => " " + padCenter2(h, widths[h]) + " ").join("|") + "|";
+  const sepLine = "|" + headers.map((h) => ":" + "-".repeat(Math.max(3, widths[h])) + ":").join("|") + "|";
+  console.log(headerLine);
+  console.log(sepLine);
   for (const row of rows) {
-    const rowLine = "|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|";
-    console.log(rowLine);
+    console.log("|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|");
   }
 }
-function loadMeta(configFile) {
+function loadDotEnv(envFile) {
+  dotenv.config({ path: path.resolve(process.cwd(), envFile), quiet: true });
+}
+function loadMeta(lang, 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 found = candidates.find((p) => fs.existsSync(p));
+  if (!found) {
+    fail(lang, "META_NOT_FOUND", [
+      t(lang, "META_TRIED"),
+      ...candidates.map((p) => `- ${p}`),
+      "",
+      t(lang, "META_TIP"),
+      "  npx zod-envkit show -c examples/env.meta.json"
+    ]);
+  }
+  const configPath = found;
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    return { meta: JSON.parse(raw), configPath };
+  } catch {
+    fail(lang, "META_PARSE_FAILED", [`- ${configPath}`]);
   }
-  const raw = fs.readFileSync(configPath, "utf8");
-  return JSON.parse(raw);
 }
 var program = new Command();
-program.name("zod-envkit").description("Env docs + runtime checks for Node.js projects");
+program.name("zod-envkit").description("Env docs + runtime checks for Node.js projects").showHelpAfterError().showSuggestionAfterError().option("--lang <lang>", "CLI language (en | ru)");
 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);
+  const lang = resolveLang(program.opts().lang);
+  const { meta } = loadMeta(lang, opts.config);
   fs.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
   fs.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
-  console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
+  console.log(t(lang, "GENERATED", { example: opts.outExample, docs: opts.outDocs }));
+  process.exit(0);
 });
-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 lang = resolveLang(program.opts().lang);
+  loadDotEnv(opts.envFile);
+  const { meta } = loadMeta(lang, opts.config);
   const rows = Object.entries(meta).map(([key, m]) => {
     const required = m.required === false ? "no" : "yes";
     const raw = process.env[key];
@@ -157,10 +206,12 @@ program.command("show").description("Show current env status (loads .env, masks
     };
   });
   printTable(rows, ["Key", "Required", "Present", "Value", "Description"]);
+  process.exit(0);
 });
 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 lang = resolveLang(program.opts().lang);
+  loadDotEnv(opts.envFile);
+  const { meta } = loadMeta(lang, opts.config);
   const missing = [];
   for (const [key, m] of Object.entries(meta)) {
     const required = m.required !== false;
@@ -169,18 +220,14 @@ program.command("check").description("Exit with code 1 if any required env var i
     if (!raw || raw.length === 0) missing.push(key);
   }
   if (missing.length) {
-    console.error("\u274C Missing required environment variables:");
+    console.error(`\u274C ${t(lang, "MISSING_ENV")}`);
     for (const k of missing) console.error(`- ${k}`);
     process.exit(1);
   }
-  console.log("\u2705 Environment looks good.");
+  console.log(`\u2705 ${t(lang, "ENV_OK")}`);
+  process.exit(0);
 });
+var known = /* @__PURE__ */ new Set(["generate", "show", "check", "-h", "--help", "-V", "--version", "--lang"]);
+var hasCommand = process.argv.slice(2).some((a) => known.has(a));
+if (!hasCommand) process.argv.splice(2, 0, "generate");
 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/dist/index.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   formatZodError: () => formatZodError,
-  loadEnv: () => loadEnv
+  loadEnv: () => loadEnv,
+  mustLoadEnv: () => mustLoadEnv
 });
 module.exports = __toCommonJS(index_exports);
 function loadEnv(schema, opts) {
@@ -30,11 +31,17 @@ function loadEnv(schema, opts) {
   if (opts?.throwOnError) throw parsed.error;
   return { ok: false, error: parsed.error };
 }
+function mustLoadEnv(schema) {
+  const res = loadEnv(schema);
+  if (res.ok) return res.env;
+  throw res.error;
+}
 function formatZodError(err) {
   return err.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   formatZodError,
-  loadEnv
+  loadEnv,
+  mustLoadEnv
 });

package/dist/index.d.cts

@@ -1,15 +1,28 @@
 import { z } from 'zod';
 
-type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
-declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: {
+type LoadEnvOptions = {
+    /**
+     * If true, throws ZodError instead of returning { ok: false }
+     */
     throwOnError?: boolean;
-}): {
+};
+type LoadEnvOk<T extends z.ZodTypeAny> = {
     ok: true;
     env: z.infer<T>;
-} | {
+};
+type LoadEnvFail = {
     ok: false;
     error: z.ZodError;
 };
+declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: LoadEnvOptions): LoadEnvOk<T> | LoadEnvFail;
+/**
+ * Convenience wrapper around loadEnv(schema, { throwOnError: true })
+ * Returns typed env or throws ZodError
+ */
+declare function mustLoadEnv<T extends z.ZodTypeAny>(schema: T): z.infer<T>;
+/**
+ * Human-friendly ZodError formatting (one issue per line)
+ */
 declare function formatZodError(err: z.ZodError): string;
 
-export { type EnvResult, formatZodError, loadEnv };
+export { type LoadEnvFail, type LoadEnvOk, type LoadEnvOptions, formatZodError, loadEnv, mustLoadEnv };

package/dist/index.d.ts

@@ -1,15 +1,28 @@
 import { z } from 'zod';
 
-type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
-declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: {
+type LoadEnvOptions = {
+    /**
+     * If true, throws ZodError instead of returning { ok: false }
+     */
     throwOnError?: boolean;
-}): {
+};
+type LoadEnvOk<T extends z.ZodTypeAny> = {
     ok: true;
     env: z.infer<T>;
-} | {
+};
+type LoadEnvFail = {
     ok: false;
     error: z.ZodError;
 };
+declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: LoadEnvOptions): LoadEnvOk<T> | LoadEnvFail;
+/**
+ * Convenience wrapper around loadEnv(schema, { throwOnError: true })
+ * Returns typed env or throws ZodError
+ */
+declare function mustLoadEnv<T extends z.ZodTypeAny>(schema: T): z.infer<T>;
+/**
+ * Human-friendly ZodError formatting (one issue per line)
+ */
 declare function formatZodError(err: z.ZodError): string;
 
-export { type EnvResult, formatZodError, loadEnv };
+export { type LoadEnvFail, type LoadEnvOk, type LoadEnvOptions, formatZodError, loadEnv, mustLoadEnv };

package/dist/index.js

@@ -5,10 +5,16 @@ function loadEnv(schema, opts) {
   if (opts?.throwOnError) throw parsed.error;
   return { ok: false, error: parsed.error };
 }
+function mustLoadEnv(schema) {
+  const res = loadEnv(schema);
+  if (res.ok) return res.env;
+  throw res.error;
+}
 function formatZodError(err) {
   return err.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
 }
 export {
   formatZodError,
-  loadEnv
+  loadEnv,
+  mustLoadEnv
 };

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "zod-envkit",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Validate environment variables with Zod and generate .env.example",
+  "license": "MIT",
+  "author": "",
+  "homepage": "https://github.com/nxtxe/zod-envkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxtxe/zod-envkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nxtxe/zod-envkit/issues"
+  },
+  "keywords": [
+    "env",
+    "dotenv",
+    "zod",
+    "validation",
+    "cli"
+  ],
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -22,39 +39,36 @@
     "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"
+    "release": "semantic-release"
   },
-  "keywords": [
-    "env",
-    "dotenv",
-    "zod",
-    "validation",
-    "cli"
-  ],
-  "author": "",
-  "license": "MIT",
   "dependencies": {
     "commander": "^13.1.0",
     "dotenv": "^17.2.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "^11.0.3",
+    "@semantic-release/release-notes-generator": "^12.1.0",
     "@types/node": "^25.0.10",
     "eslint": "^9.39.2",
+    "semantic-release": "^22.0.12",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
-  }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@9.15.9"
 }