zod-envkit 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [1.3.1](https://github.com/nxtxe/zod-envkit/compare/v1.3.0...v1.3.1) (2026-03-19)
+
+
+### Bug Fixes
+
+* **cli:** improve env error grouping and hints ([d098a70](https://github.com/nxtxe/zod-envkit/commit/d098a70683f8028b7be275bd16a580f4fccb4938))
+
+## [1.3.1](https://github.com/nxtxe/zod-envkit/compare/v1.3.0...v1.3.1) (2026-03-xx)
+
+
+### Bug Fixes
+
+* Improve `zod-envkit check` error output by grouping issues:
+  * clearly separate missing required variables and unknown variables (in strict mode)
+  * use a single `ENV_INVALID` header with structured sections instead of multiple disjoint messages
+* Add actionable hints for env meta issues:
+  * on `META_PARSE_FAILED`, show which file failed and suggest `npx zod-envkit generate -c env.meta.json`
+  * on `META_NOT_FOUND` (and no `.env.example`), suggest generating `env.meta.json` from CLI
+* Clarify strict mode behavior in unknown-variable messages:
+  * `UNKNOWN_ENV` now explicitly states that only dotenv-loaded keys are checked in `--strict` mode
+* Keep CLI contracts stable:
+  * exit codes unchanged
+  * `zod-envkit show` table format unchanged
+  * `formatZodError` output shape unchanged
+  * no JSON structures were modified
+
 # [1.3.0](https://github.com/nxtxe/zod-envkit/compare/v1.2.3...v1.3.0) (2026-03-04)
 
 

package/dist/cli/index.cjs

@@ -29,6 +29,7 @@ var import_commander = require("commander");
 // src/messages.ts
 var messages = {
   en: {
+    ENV_INVALID: "Environment is invalid.",
     META_NOT_FOUND: "env meta file not found.",
     META_TRIED: "Tried:",
     META_TIP: "Tip:",
@@ -38,7 +39,7 @@ var messages = {
     GENERATED: "Generated: {example}, {docs}",
     ENV_OK: "Environment looks good.",
     MISSING_ENV: "Missing required environment variables:",
-    UNKNOWN_ENV: "Unknown environment variables:",
+    UNKNOWN_ENV: "Unknown environment variables (strict mode; only dotenv-loaded keys):",
     INVALID_FORMAT: "Invalid docs format",
     INVALID_MASK_MODE: "Invalid mask mode",
     INVALID_SORT: "Invalid sort mode",
@@ -51,6 +52,7 @@ var messages = {
     META_HINT_SYNC_SCHEMA: "Hint: add these to your Zod schema or remove from env.meta.json."
   },
   ru: {
+    ENV_INVALID: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u0437\u0430\u0434\u0430\u043D\u044B \u043D\u0435\u043A\u043E\u0440\u0440\u0435\u043A\u0442\u043D\u043E.",
     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:",
@@ -60,7 +62,7 @@ var messages = {
     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:",
-    UNKNOWN_ENV: "\u041E\u0431\u043D\u0430\u0440\u0443\u0436\u0435\u043D\u044B \u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0435 \u043F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F:",
+    UNKNOWN_ENV: "\u041E\u0431\u043D\u0430\u0440\u0443\u0436\u0435\u043D\u044B \u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0435 \u043F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F (strict; \u0442\u043E\u043B\u044C\u043A\u043E \u0438\u0437 dotenv-\u0444\u0430\u0439\u043B\u043E\u0432):",
     INVALID_FORMAT: "\u041D\u0435\u0432\u0435\u0440\u043D\u044B\u0439 \u0444\u043E\u0440\u043C\u0430\u0442 \u0434\u043E\u043A\u0443\u043C\u0435\u043D\u0442\u0430\u0446\u0438\u0438",
     INVALID_MASK_MODE: "\u041D\u0435\u0432\u0435\u0440\u043D\u044B\u0439 \u0440\u0435\u0436\u0438\u043C \u043C\u0430\u0441\u043A\u0438\u0440\u043E\u0432\u043A\u0438",
     INVALID_SORT: "\u041D\u0435\u0432\u0435\u0440\u043D\u044B\u0439 \u0440\u0435\u0436\u0438\u043C \u0441\u043E\u0440\u0442\u0438\u0440\u043E\u0432\u043A\u0438",
@@ -160,7 +162,12 @@ function loadMeta(lang, configFile) {
       const raw = import_node_fs.default.readFileSync(found, "utf8");
       return { meta: JSON.parse(raw), configPath: found };
     } catch {
-      fail(lang, "META_PARSE_FAILED", [`- ${found}`]);
+      fail(lang, "META_PARSE_FAILED", [
+        `- ${found}`,
+        "",
+        t(lang, "META_TIP"),
+        "  Run: npx zod-envkit generate -c env.meta.json"
+      ]);
     }
   }
   const examplePath = import_node_path.default.resolve(process.cwd(), ".env.example");
@@ -175,7 +182,7 @@ function loadMeta(lang, configFile) {
     ...candidates.map((p) => `- ${p}`),
     "",
     t(lang, "META_TIP"),
-    "  npx zod-envkit show -c examples/env.meta.json"
+    "  Run: npx zod-envkit generate -c env.meta.json"
   ]);
 }
 
@@ -618,16 +625,24 @@ function registerCheck(program2, getLang2) {
     const lang = getLang2();
     const loaded = loadDotEnv(opts.dotenv);
     const { meta } = loadMeta(lang, opts.config);
+    const sections = [];
     const missing = getMissingEnv(meta, process.env);
     if (missing.length) {
-      fail(lang, "MISSING_ENV", missing.map((k) => `- ${k}`));
+      sections.push(t(lang, "MISSING_ENV"));
+      missing.forEach((k) => sections.push(`- ${k}`));
+      sections.push("");
     }
     if (opts.strict) {
       const unknown = getUnknownEnv(meta, loaded.env);
       if (unknown.length) {
-        fail(lang, "UNKNOWN_ENV", unknown.map((k) => `- ${k}`));
+        sections.push(t(lang, "UNKNOWN_ENV"));
+        unknown.forEach((k) => sections.push(`- ${k}`));
+        sections.push("");
       }
     }
+    if (sections.length) {
+      fail(lang, "ENV_INVALID", sections);
+    }
     if (opts.schema) {
       const schemaMode = String(opts.schemaMode ?? "strict").toLowerCase();
       if (schemaMode !== "warn" && schemaMode !== "strict") {

package/dist/cli/index.js

@@ -13,6 +13,7 @@ import { Command } from "commander";
 // src/messages.ts
 var messages = {
   en: {
+    ENV_INVALID: "Environment is invalid.",
     META_NOT_FOUND: "env meta file not found.",
     META_TRIED: "Tried:",
     META_TIP: "Tip:",
@@ -22,7 +23,7 @@ var messages = {
     GENERATED: "Generated: {example}, {docs}",
     ENV_OK: "Environment looks good.",
     MISSING_ENV: "Missing required environment variables:",
-    UNKNOWN_ENV: "Unknown environment variables:",
+    UNKNOWN_ENV: "Unknown environment variables (strict mode; only dotenv-loaded keys):",
     INVALID_FORMAT: "Invalid docs format",
     INVALID_MASK_MODE: "Invalid mask mode",
     INVALID_SORT: "Invalid sort mode",
@@ -35,6 +36,7 @@ var messages = {
     META_HINT_SYNC_SCHEMA: "Hint: add these to your Zod schema or remove from env.meta.json."
   },
   ru: {
+    ENV_INVALID: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u0437\u0430\u0434\u0430\u043D\u044B \u043D\u0435\u043A\u043E\u0440\u0440\u0435\u043A\u0442\u043D\u043E.",
     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:",
@@ -44,7 +46,7 @@ var messages = {
     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:",
-    UNKNOWN_ENV: "\u041E\u0431\u043D\u0430\u0440\u0443\u0436\u0435\u043D\u044B \u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0435 \u043F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F:",
+    UNKNOWN_ENV: "\u041E\u0431\u043D\u0430\u0440\u0443\u0436\u0435\u043D\u044B \u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0435 \u043F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F (strict; \u0442\u043E\u043B\u044C\u043A\u043E \u0438\u0437 dotenv-\u0444\u0430\u0439\u043B\u043E\u0432):",
     INVALID_FORMAT: "\u041D\u0435\u0432\u0435\u0440\u043D\u044B\u0439 \u0444\u043E\u0440\u043C\u0430\u0442 \u0434\u043E\u043A\u0443\u043C\u0435\u043D\u0442\u0430\u0446\u0438\u0438",
     INVALID_MASK_MODE: "\u041D\u0435\u0432\u0435\u0440\u043D\u044B\u0439 \u0440\u0435\u0436\u0438\u043C \u043C\u0430\u0441\u043A\u0438\u0440\u043E\u0432\u043A\u0438",
     INVALID_SORT: "\u041D\u0435\u0432\u0435\u0440\u043D\u044B\u0439 \u0440\u0435\u0436\u0438\u043C \u0441\u043E\u0440\u0442\u0438\u0440\u043E\u0432\u043A\u0438",
@@ -144,7 +146,12 @@ function loadMeta(lang, configFile) {
       const raw = fs.readFileSync(found, "utf8");
       return { meta: JSON.parse(raw), configPath: found };
     } catch {
-      fail(lang, "META_PARSE_FAILED", [`- ${found}`]);
+      fail(lang, "META_PARSE_FAILED", [
+        `- ${found}`,
+        "",
+        t(lang, "META_TIP"),
+        "  Run: npx zod-envkit generate -c env.meta.json"
+      ]);
     }
   }
   const examplePath = path.resolve(process.cwd(), ".env.example");
@@ -159,7 +166,7 @@ function loadMeta(lang, configFile) {
     ...candidates.map((p) => `- ${p}`),
     "",
     t(lang, "META_TIP"),
-    "  npx zod-envkit show -c examples/env.meta.json"
+    "  Run: npx zod-envkit generate -c env.meta.json"
   ]);
 }
 
@@ -397,16 +404,24 @@ function registerCheck(program2, getLang2) {
     const lang = getLang2();
     const loaded = loadDotEnv(opts.dotenv);
     const { meta } = loadMeta(lang, opts.config);
+    const sections = [];
     const missing = getMissingEnv(meta, process.env);
     if (missing.length) {
-      fail(lang, "MISSING_ENV", missing.map((k) => `- ${k}`));
+      sections.push(t(lang, "MISSING_ENV"));
+      missing.forEach((k) => sections.push(`- ${k}`));
+      sections.push("");
     }
     if (opts.strict) {
       const unknown = getUnknownEnv(meta, loaded.env);
       if (unknown.length) {
-        fail(lang, "UNKNOWN_ENV", unknown.map((k) => `- ${k}`));
+        sections.push(t(lang, "UNKNOWN_ENV"));
+        unknown.forEach((k) => sections.push(`- ${k}`));
+        sections.push("");
       }
     }
+    if (sections.length) {
+      fail(lang, "ENV_INVALID", sections);
+    }
     if (opts.schema) {
       const schemaMode = String(opts.schemaMode ?? "strict").toLowerCase();
       if (schemaMode !== "warn" && schemaMode !== "strict") {

package/package.json

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