zod-envkit 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,40 +1,70 @@
-# [1.2.0](https://github.com/nxtxe/zod-envkit/compare/v1.1.2...v1.2.0) (2026-02-16)
+## [1.2.2](https://github.com/nxtxe/zod-envkit/compare/v1.2.1...v1.2.2) (2026-02-16)
 
 
-### Features
+### Bug Fixes
 
-* stabilize preprod test suite, CLI E2E coverage, and CI pipeline ([463ea6e](https://github.com/nxtxe/zod-envkit/commit/463ea6e4676662dbbbe82bc79e0d85b079b524f8))
+* regenerate lockfile (remove stale link: specifier) ([19d243b](https://github.com/nxtxe/zod-envkit/commit/19d243b411f03c2044fae7f59e0c66676d1d1e90))
+* remove self link dependency from optionalDependencies ([3fd0568](https://github.com/nxtxe/zod-envkit/commit/3fd0568f327d112f496e357962810efdb06deaee))
 
-## [1.1.2](https://github.com/nxtxe/zod-envkit/compare/v1.1.1...v1.1.2) (2026-01-29)
+## [1.2.1](https://github.com/nxtxe/zod-envkit/compare/v1.2.0...v1.2.1) (2026-02-16)
 
 
 ### Bug Fixes
 
-* stabilize strict env validation and CI ([3055f18](https://github.com/nxtxe/zod-envkit/commit/3055f1859479212fbdc105cb0f183c6018df2376))
-* tests ([a691dab](https://github.com/nxtxe/zod-envkit/commit/a691dab0f207685bd96688e36aaabcdb5784f956))
+* strengthen CLI + env contract guarantees ([d516fbb](https://github.com/nxtxe/zod-envkit/commit/d516fbb4c8248745f7d74c1f07defaf4529c33ec))
 
 # Changelog
 
 All notable changes to this project will be documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
-## [1.1.2](https://github.com/nxtxe/zod-envkit/compare/v1.1.1...v1.1.2) (2026-01-29)
+## [1.2.0] – 2026-02-16
 
-### Bug Fixes
+### Added
 
-* **cli:** fix strict mode to validate only dotenv-loaded variables
-* **cli:** stabilize option validation and documentation links
-* **ci:** ensure CLI smoke tests and docs build in CI
-* internal cleanup to align behavior with documented API contract
+* Preprod test suite (smoke, contract, CLI E2E, robustness)
+* Strict CLI isolation for CI (no host env leakage)
+* Robust helpers for CLI E2E testing
+* Internal contract tests for public exports and exit codes
 
+### Changed
 
-## [1.1.1](https://github.com/nxtxe/zod-envkit/compare/v1.1.0...v1.1.1) (2026-01-29)
+* `init --from-meta` now generates `.env.example` from `env.meta.json`
+* Test architecture restructured under `tests/test/preprod`
+* CI workflow aligned with pnpm-only setup
+* Improved stability of strict mode behavior
 
+### Stability
 
-### Bug Fixes
+* Public API (`loadEnv`, `mustLoadEnv`, CLI flags) treated as stable contract
+* CLI exit codes verified by contract tests
+* Documentation build enforced in CI
 
-* **cli:** stabilize options validation and docs links ([640b12b](https://github.com/nxtxe/zod-envkit/commit/640b12bf95304da40c998374ba7ed08b7400e88d))
-* stabilize public API, CLI behavior, and documentation ([4604298](https://github.com/nxtxe/zod-envkit/commit/46042981f146f021919da8a4a713b2d251c542d9))
+[1.2.0]: https://www.npmjs.com/package/zod-envkit/v/1.2.0
+
+---
+
+## [1.1.2] – 2026-01-29
+
+### Fixed
+
+* Strict mode now validates only dotenv-loaded variables (prevents host env leakage)
+* Options validation and docs links stabilized
+* CI updated to include CLI smoke tests and docs build
+* Internal cleanup to align behavior with documented API contract
+
+[1.1.2]: https://www.npmjs.com/package/zod-envkit/v/1.1.2
+
+---
+
+## [1.1.1] – 2026-01-29
+
+### Fixed
+
+* Options validation and docs links stabilized
+* Public API, CLI behavior, and documentation hardened
+
+[1.1.1]: https://www.npmjs.com/package/zod-envkit/v/1.1.1
 
 ---
 
@@ -43,39 +73,31 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Added
 
 * New `zod-envkit init` command to bootstrap configuration:
-
   * generate `env.meta.json` from `.env.example`
   * generate `.env.example` from existing `env.meta.json`
 * Support for loading multiple dotenv files via `--dotenv`
-
   * example: `.env,.env.local,.env.production`
   * files are loaded in order with override semantics
 * Documentation generation in multiple formats:
-
   * `md` (default)
   * `json`
   * `yaml`
 * Sorting options for docs and CLI output via `--sort`:
-
   * `alpha`
   * `required-first`
   * `none`
 * Strict CI validation via `zod-envkit check --strict`
-
   * fails on missing **and** unknown environment variables
 * Configurable secret masking in `zod-envkit show`:
-
   * `--mask-mode partial | full | none`
   * `--no-mask` alias
 * Grouping support for environment variables via `meta.group`
 * Extended env metadata fields:
-
   * `default`
   * `deprecated`
   * `since`
   * `link`
 * New public core utilities:
-
   * `getMissingEnv`
   * `getUnknownEnv`
   * `checkEnv`
@@ -84,16 +106,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Changed
 
 * CLI architecture refactored into a modular structure (`src/cli/*`)
-
   * no breaking behavior changes
 * Documentation generator improved:
-
   * grouped sections
   * width-aware, centered markdown tables
   * extended metadata columns
 * Public API explicitly documented and treated as a stable contract
 * CLI default behavior preserved:
-
   * running `zod-envkit` without subcommand defaults to `generate`
 
 ### Fixed
@@ -119,13 +138,11 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 * Public API stabilized and separated from CLI internals
 * CLI error handling improved:
-
   * no stack traces for user errors
   * consistent human-readable messages
   * strict exit codes
 * `ENV.md` generation now produces centered, width-aware tables
 * CLI now reliably resolves `env.meta.json` from:
-
   * project root
   * `./examples/`
   * explicit `-c/--config`
@@ -184,7 +201,6 @@ This project follows [Semantic Versioning](https://semver.org/).
 * Type-safe env validation with Zod
 * `loadEnv` and `formatZodError`
 * CLI to generate:
-
   * `.env.example`
   * `ENV.md`
 * ESM and CommonJS builds

package/README.RU.md

@@ -16,90 +16,80 @@
     </a>
   </p>
 
+
   <p>
     <a href="./README.md">English</a> |
     <a href="./README.RU.md">Русский</a>
   </p>
 </div>
 
-Типобезопасная валидация и документация переменных окружения с помощью **Zod**.
 
-**zod-envkit** — это небольшая, явная библиотека + CLI, которая помогает воспринимать переменные окружения как  
-**явный runtime-контракт**, а не как неявную игру в угадайку.
+Типобезопасная валидация и документация переменных окружения с помощью Zod.
 
-- валидация `process.env` при старте приложения
-- полностью типизированные переменные окружения
-- генерация `.env.example`
-- генерация документации (`ENV.md`, `ENV.json`, `ENV.yaml`)
-- просмотр состояния env через CLI (с маскированием секретов)
-- строгая проверка env в CI/CD
-- инициализация конфигурации через `zod-envkit init`
-- загрузка нескольких `.env*` файлов с приоритетом
+zod-envkit — это небольшая, явная библиотека + CLI, которая рассматривает переменные окружения как
+явный runtime-контракт, а не как неявную игру в угадайку.
+	•	валидирует process.env при старте приложения
+	•	предоставляет полностью типизированные переменные окружения
+	•	генерирует .env.example
+	•	генерирует документацию (ENV.md, ENV.json, ENV.yaml)
+	•	позволяет просматривать состояние env через CLI (с маскированием секретов)
+	•	строго валидирует env в CI/CD
+	•	инициализирует конфигурацию через zod-envkit init
+	•	загружает несколько .env* файлов с приоритетом
 
 Никакого облака. Никакой магии. Только код.
 
----
+⸻
 
-## Зачем
+Зачем
 
-Переменные окружения критичны, но почти всегда обрабатываются плохо.
+Переменные окружения критичны, но обычно обрабатываются неправильно.
 
 Типичные проблемы:
+	•	process.env — это просто string | undefined
+	•	отсутствующие или некорректные переменные ломают приложение во время выполнения
+	•	.env.example и документация рассинхронизируются
+	•	CI/CD падает поздно и непредсказуемо
 
-- `process.env` — это просто `string | undefined`
-- отсутствующие или некорректные переменные ломают приложение **во время выполнения**
-- `.env.example` и документация быстро устаревают
-- CI/CD падает поздно и непредсказуемо
-
-**zod-envkit** решает это, делая env:
-
-- валидируемым на раннем этапе
-- типизированным
-- документированным
-- проверяемым в CI
-
----
+zod-envkit решает это, делая env:
+	•	валидируемым на раннем этапе
+	•	типизированным
+	•	документированным
+	•	проверяемым в CI
 
-## Когда использовать
+⸻
 
-Используйте **zod-envkit**, если:
+Когда использовать
 
-- ошибки env должны обнаруживаться **при старте**, а не в продакшене
-- вы используете TypeScript и хотите строгие типы
-- `.env.example` и документация должны генерироваться из одного источника
-- CI должен падать при отсутствии или лишних переменных
+Используйте zod-envkit, если:
+	•	вы хотите, чтобы ошибки env обнаруживались при старте, а не в продакшене
+	•	вы используете TypeScript и вам важны корректные типы
+	•	вы хотите получать .env.example и документацию из единого источника правды
+	•	вы хотите, чтобы CI ловил отсутствующие или лишние переменные
 
-## Когда НЕ использовать
+Когда НЕ использовать
 
-Не стоит использовать **zod-envkit**, если:
+Не стоит использовать zod-envkit, если:
+	•	ваш проект очень маленький и неформальный
+	•	вы вообще не контролируете переменные окружения
+	•	вы ожидаете автоматическую интроспекцию схем или “магическое” поведение
 
-- проект очень маленький и неформальный
-- вы не контролируете переменные окружения
-- вы ожидаете “магическую” автогенерацию схем
+⸻
 
----
+Установка
 
-## Установка
-
-```bash
 npm install zod-envkit
-````
-
-```bash
 yarn add zod-envkit
-```
-
-```bash
 pnpm add zod-envkit
-```
+bun add zod-envkit
 
----
 
-## Использование библиотеки (runtime-валидация)
+⸻
+
+Использование библиотеки (runtime-валидация)
 
 Создайте один файл, отвечающий за загрузку и валидацию env.
 
-```ts
 import "dotenv/config";
 import { z } from "zod";
 import { loadEnv, mustLoadEnv, formatZodError } from "zod-envkit";
@@ -109,11 +99,9 @@ const EnvSchema = z.object({
   PORT: z.coerce.number().int().min(1).max(65535),
   DATABASE_URL: z.string().url(),
 });
-```
 
-### Безопасный режим (без исключений)
+Безопасный режим (без исключений)
 
-```ts
 const result = loadEnv(EnvSchema);
 
 if (!result.ok) {
@@ -122,37 +110,31 @@ if (!result.ok) {
 }
 
 export const env = result.env;
-```
 
-### Fail-fast режим (рекомендуется)
+Fail-fast режим (рекомендуется)
 
-```ts
 export const env = mustLoadEnv(EnvSchema);
-```
 
 Теперь:
+	•	env.PORT — это number
+	•	env.DATABASE_URL — это string
+	•	TypeScript знает всё на этапе компиляции
+	•	приложение падает сразу, если env некорректен
 
-* `env.PORT` — это **number**
-* `env.DATABASE_URL` — это **string**
-* TypeScript всё знает на этапе компиляции
-* приложение падает сразу, если env некорректен
-
----
+⸻
 
-## Использование CLI
+Использование CLI
 
-CLI работает на основе мета-файла: `env.meta.json`.
+CLI работает на основе мета-файла: env.meta.json.
 
 По умолчанию он ищется в:
+	•	./env.meta.json
+	•	./examples/env.meta.json
 
-* `./env.meta.json`
-* `./examples/env.meta.json`
+⸻
 
----
+Пример env.meta.json
 
-## Пример `env.meta.json`
-
-```json
 {
   "NODE_ENV": {
     "description": "Режим выполнения",
@@ -170,164 +152,165 @@ CLI работает на основе мета-файла: `env.meta.json`.
     "required": true
   }
 }
-```
 
----
 
-## Команды CLI
+⸻
+
+Команды CLI
 
-### Генерация `.env.example` и документации
+Генерация .env.example и документации
 
 (Поведение по умолчанию)
 
-```bash
 npx zod-envkit
-```
 
 или явно:
 
-```bash
 npx zod-envkit generate
-```
 
 Генерация документации в разных форматах:
 
-```bash
 npx zod-envkit generate --format json
 npx zod-envkit generate --format yaml
-```
 
-Сортировка переменных:
+Управление сортировкой:
 
-```bash
 npx zod-envkit generate --sort alpha
 npx zod-envkit generate --sort required-first
-```
 
----
 
-### Просмотр текущего состояния окружения
+⸻
+
+Просмотр текущего состояния окружения
 
 Загружает dotenv-файлы, маскирует секреты и выводит читаемую таблицу.
 
-```bash
 npx zod-envkit show
-```
 
 Дополнительные опции:
 
-```bash
 npx zod-envkit show --mask-mode full
 npx zod-envkit show --no-mask
 npx zod-envkit show --dotenv ".env,.env.local,.env.production"
-```
 
----
 
-### Проверка окружения (удобно для CI)
+⸻
+
+Проверка окружения (удобно для CI)
 
-```bash
 npx zod-envkit check
-```
 
-Строгий режим:
+Строгий режим (падает при неизвестных переменных):
 
-```bash
 npx zod-envkit check --strict
-```
 
-* завершает процесс с кодом `1`, если отсутствуют обязательные переменные
-* в `--strict` режиме также падает при наличии неизвестных переменных
+	•	завершает процесс с кодом 1, если отсутствуют обязательные переменные
+	•	в --strict режиме также падает при наличии неизвестных переменных
 
----
+⸻
 
-### Инициализация конфигурации
+Инициализация конфигурации
 
 Быстрый старт конфигурации из существующих файлов.
 
-Сгенерировать `env.meta.json` из `.env.example`:
+Сгенерировать env.meta.json из .env.example:
 
-```bash
 npx zod-envkit init
-```
 
-Сгенерировать `.env.example` из существующего `env.meta.json`:
+Сгенерировать .env.example из существующего env.meta.json:
 
-```bash
 npx zod-envkit init --from-meta
-```
 
----
 
-## Стабильность и версионирование
+⸻
+
+Стабильность и версионирование
 
-`zod-envkit` следует **Semantic Versioning**.
+zod-envkit следует Semantic Versioning.
 
-### Стабильный public API (1.x)
+Стабильность Public API (1.x)
 
-**Библиотека:**
+Всё перечисленное ниже считается стабильным public API в рамках всей ветки 1.x.
 
-* `loadEnv`
-* `mustLoadEnv`
-* `formatZodError`
-* `checkEnv`
-* `getMissingEnv`
-* `getUnknownEnv`
-* `isSecretKey`
-* `generateEnvExample`
-* `generateEnvDocs`
+Экспорты библиотеки (entrypoint zod-envkit):
+	•	loadEnv
+	•	mustLoadEnv
+	•	formatZodError
+	•	checkEnv
+	•	getMissingEnv
+	•	getUnknownEnv
+	•	isSecretKey
+	•	generateEnvExample
+	•	generateEnvDocs
+	•	sortMetaEntries
+	•	связанные публичные типы: EnvMeta, EnvMetaEntry, EnvCheckResult, GenerateDocsOptions, DocsFormat, SortMode
 
-**CLI:**
+CLI-контракт:
+	•	команды: generate, show, check, init
+	•	задокументированные флаги и значения по умолчанию
+	•	поведение exit-кодов (успех = 0, пользовательская ошибка = 1)
 
-* `generate`, `show`, `check`, `init`
-* задокументированные флаги и коды выхода
+Политика breaking-изменений
 
-### Что считается breaking change
+Breaking change (major) включает:
+	•	изменение сигнатур или структуры возвращаемых значений стабильных экспортов
+	•	удаление или переименование public-экспортов
+	•	удаление или переименование CLI-команд или флагов
+	•	изменение поведения CLI по умолчанию
+	•	изменение семантики exit-кодов
+	•	изменение контрактов формата вывода, ломающих существующие инструменты
 
-* изменение сигнатур или типов возвращаемых значений
-* удаление или переименование public-экспортов
-* удаление или переименование CLI-команд и флагов
-* изменение семантики exit-кодов
-* изменение поведения CLI по умолчанию
+Не считается breaking (minor/patch):
+	•	добавление новых экспортов (обратно совместимых)
+	•	добавление новых CLI-флагов (обратно совместимых)
+	•	добавление новых опциональных полей в env.meta.json
+	•	улучшение сообщений об ошибках или форматирования документации без нарушения совместимости
 
-Не считается breaking:
+⸻
 
-* добавление новых опциональных возможностей
-* добавление новых флагов
-* улучшение форматирования и сообщений об ошибках
+Что нового в 1.2.0
 
----
+Версия 1.2.0 сосредоточена на надёжности, контрактности и готовности к CI.
 
-## Почему не просто dotenv?
+Основные изменения:
+	•	усилено поведение строгого режима (check --strict) для CI
+	•	детерминированная обработка приоритета dotenv-файлов
+	•	улучшены гарантии маскирования секретов в show
+	•	расширен preprod-набор тестов (smoke, contract, CLI E2E, robustness)
+	•	CI-pipeline принудительно выполняет: build → tests → docs build
 
-`dotenv`:
+С этого момента zod-envkit — это не просто “утилита”, а
+стабильный инструмент контрактов окружения для CI/CD-пайплайнов.
 
-* ❌ нет валидации
-* ❌ нет типов
-* ❌ нет документации
-* ❌ нет проверок для CI
+⸻
 
-`zod-envkit`:
+Почему не просто dotenv?
 
-* ✅ валидация
-* ✅ вывод типов для TypeScript
-* ✅ документация
-* ✅ CLI-инструменты
+dotenv:
+	•	❌ нет валидации
+	•	❌ нет типов
+	•	❌ нет документации
+	•	❌ нет проверок для CI
 
-Они предназначены для использования **вместе**.
+zod-envkit:
+	•	✅ валидация
+	•	✅ вывод типов для TypeScript
+	•	✅ документация
+	•	✅ CLI-инструменты
 
----
+Они предназначены для использования вместе.
 
-## Принципы дизайна
+⸻
 
-* явная конфигурация вместо магии
-* отсутствие привязки к фреймворкам
-* маленький и предсказуемый API
-* библиотека и CLI независимы, но дополняют друг друга
-* переменные окружения — это runtime-контракт
+Принципы дизайна
+	•	явная конфигурация вместо магии
+	•	отсутствие привязки к фреймворкам
+	•	маленький и предсказуемый API
+	•	библиотека и CLI независимы, но дополняют друг друга
+	•	переменные окружения — это runtime-контракт
 
----
+⸻
 
-## Лицензия
+Лицензия
 
 MIT

package/README.md

@@ -83,16 +83,10 @@ Skip **zod-envkit** if:
 
 ```bash
 npm install zod-envkit
-````
-
-```bash
 yarn add zod-envkit
-```
-
-```bash
 pnpm add zod-envkit
+bun add zod-envkit
 ```
-
 ---
 
 ## Library usage (runtime validation)
@@ -263,38 +257,62 @@ npx zod-envkit init --from-meta
 
 `zod-envkit` follows **Semantic Versioning**.
 
-### Stable public API (1.x)
+### Public API stability (1.x)
+
+Everything listed below is treated as **stable public API** for the whole 1.x line.
+
+**Library exports (entrypoint `zod-envkit`):**
+
+- `loadEnv`
+- `mustLoadEnv`
+- `formatZodError`
+- `checkEnv`
+- `getMissingEnv`
+- `getUnknownEnv`
+- `isSecretKey`
+- `generateEnvExample`
+- `generateEnvDocs`
+- `sortMetaEntries`
+- related public types: `EnvMeta`, `EnvMetaEntry`, `EnvCheckResult`, `GenerateDocsOptions`, `DocsFormat`, `SortMode`
+
+**CLI contract:**
+
+- commands: `generate`, `show`, `check`, `init`
+- documented flags and defaults
+- exit code behavior (success = `0`, user error = `1`)
+
+### Breaking change policy
+
+A **breaking** change (major) includes:
 
-**Library:**
+- changing signatures or return shapes of the stable exports
+- removing/renaming public exports
+- removing/renaming CLI commands or flags
+- changing CLI default behavior (e.g. what `zod-envkit` does with no args)
+- changing exit code semantics
+- changing output format contracts in a way that breaks existing tooling
 
-* `loadEnv`
-* `mustLoadEnv`
-* `formatZodError`
-* `checkEnv`
-* `getMissingEnv`
-* `getUnknownEnv`
-* `isSecretKey`
-* `generateEnvExample`
-* `generateEnvDocs`
+A **non-breaking** change (minor/patch) includes:
 
-**CLI:**
+- adding new exports (backwards compatible)
+- adding new CLI flags (backwards compatible)
+- adding new optional fields to `env.meta.json`
+- improving error messages or docs output while keeping it valid
 
-* `generate`, `show`, `check`, `init`
-* documented flags and exit codes
+### What’s new in 1.2.0
 
-### What is considered breaking
+Version **1.2.0** focuses on reliability, contract enforcement, and CI readiness.
 
-* changing function signatures or return types
-* removing or renaming public exports
-* removing or renaming CLI commands or flags
-* changing exit code semantics
-* changing default CLI behavior
+Highlights:
 
-Non-breaking:
+- hardened strict mode behavior (`check --strict`) for CI usage
+- deterministic dotenv priority handling
+- improved secret masking guarantees in `show`
+- expanded preprod test suite (smoke, contract, CLI E2E, robustness)
+- CI pipeline enforces: build → tests → docs build
 
-* adding new optional features
-* adding new flags
-* improving error messages or formatting
+This is the point where `zod-envkit` stops being “just a helper” and becomes a
+**stable environment contract tool for CI/CD pipelines**.
 
 ---
 
@@ -302,17 +320,17 @@ Non-breaking:
 
 `dotenv`:
 
-* ❌ no validation
-* ❌ no types
-* ❌ no documentation
-* ❌ no CI checks
+- ❌ no validation
+- ❌ no types
+- ❌ no documentation
+- ❌ no CI checks
 
 `zod-envkit`:
 
-* ✅ validation
-* ✅ TypeScript inference
-* ✅ documentation
-* ✅ CLI tooling
+- ✅ validation
+- ✅ TypeScript inference
+- ✅ documentation
+- ✅ CLI tooling
 
 They are designed to be used **together**.
 
@@ -320,11 +338,11 @@ They are designed to be used **together**.
 
 ## Design principles
 
-* explicit configuration over magic
-* no framework coupling
-* small and predictable API
-* library and CLI are independent but complementary
-* environment variables are a runtime contract
+- explicit configuration over magic
+- no framework coupling
+- small and predictable API
+- library and CLI are independent but complementary
+- environment variables are a runtime contract
 
 ---
 

package/dist/cli/index.cjs

@@ -77,9 +77,16 @@ function t(lang, key, vars) {
 
 // src/cli/lib/argv.ts
 function injectDefaultCommandIfMissing(argv, opts) {
+  if (argv.length <= 2) {
+    argv.splice(2, 0, opts.defaultCommand);
+    return;
+  }
   const args = argv.slice(2);
   const hasKnownToken = args.some((a) => opts.known.has(a));
-  if (!hasKnownToken) argv.splice(2, 0, opts.defaultCommand);
+  const alreadyInjected = args[0] === opts.defaultCommand;
+  if (!hasKnownToken && !alreadyInjected) {
+    argv.splice(2, 0, opts.defaultCommand);
+  }
 }
 
 // src/cli/commands/generate.ts
@@ -409,36 +416,54 @@ function maskValue(key, value, mode) {
 }
 
 // src/cli/lib/table.ts
+function strLen2(s) {
+  return (s ?? "").length;
+}
 function padCenter2(text, width) {
   const v = text ?? "";
-  const diff = width - v.length;
+  const diff = width - strLen2(v);
   if (diff <= 0) return v;
   const left = Math.floor(diff / 2);
   const right = diff - left;
   return " ".repeat(left) + v + " ".repeat(right);
 }
+function makeDivider2(width, align) {
+  const w = Math.max(3, width);
+  if (align === "center") return ":" + "-".repeat(w - 2) + ":";
+  if (align === "right") return "-".repeat(w - 1) + ":";
+  return "-".repeat(w);
+}
 function printMarkdownTable(rows, headers) {
+  if (headers.length === 0) return;
   const widths = {};
-  for (const h of headers) widths[h] = h.length;
+  for (const h of headers) widths[h] = strLen2(h);
   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], strLen2(row[h] ?? ""));
+    }
   }
   for (const h of headers) widths[h] += 2;
-  const headerLine = "|" + headers.map((h) => " " + padCenter2(h, widths[h]) + " ").join("|") + "|";
-  const sepLine = "|" + headers.map((h) => ":" + "-".repeat(Math.max(3, widths[h])) + ":").join("|") + "|";
+  const headerLine = "|" + headers.map((h) => ` ${padCenter2(h, widths[h])} `).join("|") + "|";
+  const sepLine = "|" + headers.map((h) => ` ${makeDivider2(widths[h], "center")} `).join("|") + "|";
   console.log(headerLine);
   console.log(sepLine);
   for (const row of rows) {
-    console.log("|" + headers.map((h) => " " + padCenter2(row[h] ?? "", widths[h]) + " ").join("|") + "|");
+    console.log(
+      "|" + headers.map((h) => ` ${padCenter2(row[h] ?? "", widths[h])} `).join("|") + "|"
+    );
   }
 }
 
 // src/cli/lib/sort.ts
 function sortKeys(meta, sort) {
   const keys = Object.keys(meta);
-  if (sort === "none") return keys;
-  if (sort === "alpha") return keys.sort((a, b) => a.localeCompare(b));
-  return keys.sort((a, b) => {
+  if (sort === "none") {
+    return [...keys];
+  }
+  if (sort === "alpha") {
+    return [...keys].sort((a, b) => a.localeCompare(b));
+  }
+  return [...keys].sort((a, b) => {
     const ar = meta[a]?.required === false ? 1 : 0;
     const br = meta[b]?.required === false ? 1 : 0;
     if (ar !== br) return ar - br;
@@ -457,7 +482,7 @@ function registerShow(program2, getLang2) {
   program2.command("show").description("Show current env status (loads dotenv, masks secrets)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--dotenv <list>", "Comma-separated dotenv files (default: .env)", ".env").option("--mask-mode <mode>", "Mask mode (partial | full | none)", "partial").option("--no-mask", "Alias for --mask-mode none").option("--sort <mode>", "Sort mode (alpha | required-first | none)", "none").action((opts) => {
     const lang = getLang2();
     loadDotEnv(String(opts.dotenv ?? ".env"));
-    const { meta } = loadMeta(lang, opts.config);
+    const { meta } = loadMeta(lang, String(opts.config ?? "env.meta.json"));
     const fallbackMode = opts.mask === false ? "none" : "partial";
     const modeRaw = String(opts.maskMode ?? fallbackMode);
     if (!isMaskMode(modeRaw)) {
@@ -499,16 +524,12 @@ function registerCheck(program2, getLang2) {
     const { meta } = loadMeta(lang, opts.config);
     const missing = getMissingEnv(meta, process.env);
     if (missing.length) {
-      console.error(`\u274C ${t(lang, "MISSING_ENV")}`);
-      for (const k of missing) console.error(`- ${k}`);
-      process.exit(1);
+      fail(lang, "MISSING_ENV", missing.map((k) => `- ${k}`));
     }
     if (opts.strict) {
       const unknown = getUnknownEnv(meta, loaded.env);
       if (unknown.length) {
-        console.error(`\u274C ${t(lang, "UNKNOWN_ENV")}`);
-        for (const k of unknown) console.error(`- ${k}`);
-        process.exit(1);
+        fail(lang, "UNKNOWN_ENV", unknown.map((k) => `- ${k}`));
       }
     }
     console.log(`\u2705 ${t(lang, "ENV_OK")}`);
@@ -552,7 +573,7 @@ function registerInit(program2, getLang2) {
     }
     const env = readEnvFile(input);
     if (Object.keys(env).length === 0) {
-      fail(lang, "META_PARSE_FAILED", [`- ${t(lang, "INIT_INPUT_EMPTY")} ${input}`]);
+      fail(lang, "INIT_INPUT_EMPTY", [`- ${input}`]);
     }
     const meta = metaFromEnv(env, opts.group ? String(opts.group) : void 0);
     import_node_fs4.default.writeFileSync(output, JSON.stringify(meta, null, 2) + "\n", "utf8");

package/dist/cli/index.js

@@ -61,9 +61,16 @@ function t(lang, key, vars) {
 
 // src/cli/lib/argv.ts
 function injectDefaultCommandIfMissing(argv, opts) {
+  if (argv.length <= 2) {
+    argv.splice(2, 0, opts.defaultCommand);
+    return;
+  }
   const args = argv.slice(2);
   const hasKnownToken = args.some((a) => opts.known.has(a));
-  if (!hasKnownToken) argv.splice(2, 0, opts.defaultCommand);
+  const alreadyInjected = args[0] === opts.defaultCommand;
+  if (!hasKnownToken && !alreadyInjected) {
+    argv.splice(2, 0, opts.defaultCommand);
+  }
 }
 
 // src/cli/commands/generate.ts
@@ -197,36 +204,54 @@ function maskValue(key, value, mode) {
 }
 
 // src/cli/lib/table.ts
+function strLen(s) {
+  return (s ?? "").length;
+}
 function padCenter(text, width) {
   const v = text ?? "";
-  const diff = width - v.length;
+  const diff = width - strLen(v);
   if (diff <= 0) return v;
   const left = Math.floor(diff / 2);
   const right = diff - left;
   return " ".repeat(left) + v + " ".repeat(right);
 }
+function makeDivider(width, align) {
+  const w = Math.max(3, width);
+  if (align === "center") return ":" + "-".repeat(w - 2) + ":";
+  if (align === "right") return "-".repeat(w - 1) + ":";
+  return "-".repeat(w);
+}
 function printMarkdownTable(rows, headers) {
+  if (headers.length === 0) return;
   const widths = {};
-  for (const h of headers) widths[h] = h.length;
+  for (const h of headers) widths[h] = strLen(h);
   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], strLen(row[h] ?? ""));
+    }
   }
   for (const h of headers) widths[h] += 2;
-  const headerLine = "|" + headers.map((h) => " " + padCenter(h, widths[h]) + " ").join("|") + "|";
-  const sepLine = "|" + headers.map((h) => ":" + "-".repeat(Math.max(3, widths[h])) + ":").join("|") + "|";
+  const headerLine = "|" + headers.map((h) => ` ${padCenter(h, widths[h])} `).join("|") + "|";
+  const sepLine = "|" + headers.map((h) => ` ${makeDivider(widths[h], "center")} `).join("|") + "|";
   console.log(headerLine);
   console.log(sepLine);
   for (const row of rows) {
-    console.log("|" + headers.map((h) => " " + padCenter(row[h] ?? "", widths[h]) + " ").join("|") + "|");
+    console.log(
+      "|" + headers.map((h) => ` ${padCenter(row[h] ?? "", widths[h])} `).join("|") + "|"
+    );
   }
 }
 
 // src/cli/lib/sort.ts
 function sortKeys(meta, sort) {
   const keys = Object.keys(meta);
-  if (sort === "none") return keys;
-  if (sort === "alpha") return keys.sort((a, b) => a.localeCompare(b));
-  return keys.sort((a, b) => {
+  if (sort === "none") {
+    return [...keys];
+  }
+  if (sort === "alpha") {
+    return [...keys].sort((a, b) => a.localeCompare(b));
+  }
+  return [...keys].sort((a, b) => {
     const ar = meta[a]?.required === false ? 1 : 0;
     const br = meta[b]?.required === false ? 1 : 0;
     if (ar !== br) return ar - br;
@@ -245,7 +270,7 @@ function registerShow(program2, getLang2) {
   program2.command("show").description("Show current env status (loads dotenv, masks secrets)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--dotenv <list>", "Comma-separated dotenv files (default: .env)", ".env").option("--mask-mode <mode>", "Mask mode (partial | full | none)", "partial").option("--no-mask", "Alias for --mask-mode none").option("--sort <mode>", "Sort mode (alpha | required-first | none)", "none").action((opts) => {
     const lang = getLang2();
     loadDotEnv(String(opts.dotenv ?? ".env"));
-    const { meta } = loadMeta(lang, opts.config);
+    const { meta } = loadMeta(lang, String(opts.config ?? "env.meta.json"));
     const fallbackMode = opts.mask === false ? "none" : "partial";
     const modeRaw = String(opts.maskMode ?? fallbackMode);
     if (!isMaskMode(modeRaw)) {
@@ -287,16 +312,12 @@ function registerCheck(program2, getLang2) {
     const { meta } = loadMeta(lang, opts.config);
     const missing = getMissingEnv(meta, process.env);
     if (missing.length) {
-      console.error(`\u274C ${t(lang, "MISSING_ENV")}`);
-      for (const k of missing) console.error(`- ${k}`);
-      process.exit(1);
+      fail(lang, "MISSING_ENV", missing.map((k) => `- ${k}`));
     }
     if (opts.strict) {
       const unknown = getUnknownEnv(meta, loaded.env);
       if (unknown.length) {
-        console.error(`\u274C ${t(lang, "UNKNOWN_ENV")}`);
-        for (const k of unknown) console.error(`- ${k}`);
-        process.exit(1);
+        fail(lang, "UNKNOWN_ENV", unknown.map((k) => `- ${k}`));
       }
     }
     console.log(`\u2705 ${t(lang, "ENV_OK")}`);
@@ -340,7 +361,7 @@ function registerInit(program2, getLang2) {
     }
     const env = readEnvFile(input);
     if (Object.keys(env).length === 0) {
-      fail(lang, "META_PARSE_FAILED", [`- ${t(lang, "INIT_INPUT_EMPTY")} ${input}`]);
+      fail(lang, "INIT_INPUT_EMPTY", [`- ${input}`]);
     }
     const meta = metaFromEnv(env, opts.group ? String(opts.group) : void 0);
     fs4.writeFileSync(output, JSON.stringify(meta, null, 2) + "\n", "utf8");

package/dist/index.d.cts

@@ -149,7 +149,7 @@ declare function generateEnvDocs(meta: EnvMeta, opts?: GenerateDocsOptions): str
  * - `unknown`: keys present in env but not described in meta
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 type EnvCheckResult = {
     ok: boolean;
@@ -160,7 +160,7 @@ type EnvCheckResult = {
  * Return required keys from `meta` that are missing (or empty) in `env`.
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function getMissingEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[];
 /**
@@ -169,7 +169,7 @@ declare function getMissingEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[]
  * Note: the result is returned in stable alphabetical order.
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function getUnknownEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[];
 /**
@@ -178,7 +178,7 @@ declare function getUnknownEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[]
  * Used by the CLI to mask values (TOKEN/SECRET/PASSWORD/*_KEY/PRIVATE).
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function isSecretKey(key: string): boolean;
 /**
@@ -188,12 +188,14 @@ declare function isSecretKey(key: string): boolean;
  *
  * Note: `ok` here means:
  * - no missing required vars
- * - no unknown vars (because this function is strict by definition)
+ * - no unknown vars
+ *
+ * The CLI may choose to ignore `unknown` unless `--strict` is enabled.
  *
  * If you want "missing only" checks, use {@link getMissingEnv}.
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function checkEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): EnvCheckResult;
 

package/dist/index.d.ts

@@ -149,7 +149,7 @@ declare function generateEnvDocs(meta: EnvMeta, opts?: GenerateDocsOptions): str
  * - `unknown`: keys present in env but not described in meta
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 type EnvCheckResult = {
     ok: boolean;
@@ -160,7 +160,7 @@ type EnvCheckResult = {
  * Return required keys from `meta` that are missing (or empty) in `env`.
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function getMissingEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[];
 /**
@@ -169,7 +169,7 @@ declare function getMissingEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[]
  * Note: the result is returned in stable alphabetical order.
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function getUnknownEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[];
 /**
@@ -178,7 +178,7 @@ declare function getUnknownEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[]
  * Used by the CLI to mask values (TOKEN/SECRET/PASSWORD/*_KEY/PRIVATE).
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function isSecretKey(key: string): boolean;
 /**
@@ -188,12 +188,14 @@ declare function isSecretKey(key: string): boolean;
  *
  * Note: `ok` here means:
  * - no missing required vars
- * - no unknown vars (because this function is strict by definition)
+ * - no unknown vars
+ *
+ * The CLI may choose to ignore `unknown` unless `--strict` is enabled.
  *
  * If you want "missing only" checks, use {@link getMissingEnv}.
  *
  * @public
- * @since 1.1.0
+ * @since 1.2.0
  */
 declare function checkEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): EnvCheckResult;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-envkit",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Validate environment variables with Zod and generate .env.example",
   "license": "MIT",
   "author": "",