zod-envkit 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [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)
+
+
+### Features
+
+* polish examples and install docs for 1.3.0 ([182ed34](https://github.com/nxtxe/zod-envkit/commit/182ed349f60c2e7cacb002f12c3a3642001eb19e))
+
 ## [1.2.3](https://github.com/nxtxe/zod-envkit/compare/v1.2.2...v1.2.3) (2026-02-19)
 
 
@@ -20,10 +53,6 @@
 
 * 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.2.0] – 2026-02-16
 
@@ -223,3 +252,9 @@ This project follows [Semantic Versioning](https://semver.org/).
 * Small, framework-agnostic core
 
 [1.0.0]: https://www.npmjs.com/package/zod-envkit/v/1.0.0
+
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+This project follows [Semantic Versioning](https://semver.org/).

package/dist/{chunk-RI23O6XK.js → chunk-J4V5ODI6.js}

@@ -57,7 +57,7 @@ function generateEnvExample(meta) {
 function buildRows(entries) {
   return entries.map(([key, m]) => {
     const req = m.required === false ? "no" : "yes";
-    const dep = m.deprecated ? "\u26A0\uFE0F" : "";
+    const dep = m.deprecated === true ? "\u26A0\uFE0F" : typeof m.deprecated === "string" ? `\u26A0\uFE0F ${m.deprecated}` : "";
     const link = m.link ? m.link : "";
     return {
       Key: key,
@@ -182,16 +182,25 @@ function getUnknownEnv(meta, env = process.env) {
   return unknown;
 }
 var SECRET_PATTERNS = [
-  (k) => k.includes("TOKEN"),
   (k) => k.includes("SECRET"),
   (k) => k.includes("PASSWORD"),
+  (k) => k.includes("PASS"),
+  (k) => k.includes("PWD"),
   (k) => k.includes("PRIVATE"),
   (k) => k.includes("API_KEY"),
-  (k) => k.endsWith("_KEY")
+  (k) => k.endsWith("_KEY"),
+  (k) => k === "KEY",
+  (k) => k === "API",
+  (k) => k.includes("TOKEN"),
+  (k) => k.includes("JWT"),
+  (k) => k.includes("SESSION"),
+  (k) => k.includes("CREDENTIAL"),
+  (k) => k.includes("CREDS"),
+  (k) => k.includes("DATABASE_URL") || k === "DB_URL",
+  (k) => k.includes("CONNECTION_STRING")
 ];
 function isSecretKey(key) {
-  const k = key.toUpperCase();
-  return SECRET_PATTERNS.some((fn) => fn(k));
+  return SECRET_PATTERNS.some((fn) => fn(key.toUpperCase()));
 }
 function checkEnv(meta, env = process.env) {
   const missing = getMissingEnv(meta, env);

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,13 +39,20 @@ 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",
-    INIT_INPUT_EMPTY: "Input env file is empty or not found:"
+    INIT_INPUT_EMPTY: "Input env file is empty or not found:",
+    SCHEMA_LOAD_FAILED: "Failed to load schema file:",
+    SCHEMA_NOT_OBJECT: "Schema file must export a Zod object (z.object(...)).",
+    SCHEMA_VARS_NOT_IN_META: "Schema variables not listed in env.meta.json:",
+    META_VARS_NOT_IN_SCHEMA: "env.meta.json variables not in schema:",
+    SCHEMA_HINT_ADD_TO_META: "Hint: add these keys to env.meta.json for docs and CLI.",
+    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:",
@@ -54,11 +62,17 @@ 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",
-    INIT_INPUT_EMPTY: "\u0424\u0430\u0439\u043B \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u043F\u0443\u0441\u0442 \u0438\u043B\u0438 \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D:"
+    INIT_INPUT_EMPTY: "\u0424\u0430\u0439\u043B \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u043F\u0443\u0441\u0442 \u0438\u043B\u0438 \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D:",
+    SCHEMA_LOAD_FAILED: "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u0437\u0430\u0433\u0440\u0443\u0437\u0438\u0442\u044C \u0444\u0430\u0439\u043B \u0441\u0445\u0435\u043C\u044B:",
+    SCHEMA_NOT_OBJECT: "\u0424\u0430\u0439\u043B \u0441\u0445\u0435\u043C\u044B \u0434\u043E\u043B\u0436\u0435\u043D \u044D\u043A\u0441\u043F\u043E\u0440\u0442\u0438\u0440\u043E\u0432\u0430\u0442\u044C Zod object (z.object(...)).",
+    SCHEMA_VARS_NOT_IN_META: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u0441\u0445\u0435\u043C\u044B \u043E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u044E\u0442 \u0432 env.meta.json:",
+    META_VARS_NOT_IN_SCHEMA: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 env.meta.json \u043E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u044E\u0442 \u0432 \u0441\u0445\u0435\u043C\u0435:",
+    SCHEMA_HINT_ADD_TO_META: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430: \u0434\u043E\u0431\u0430\u0432\u044C\u0442\u0435 \u044D\u0442\u0438 \u043A\u043B\u044E\u0447\u0438 \u0432 env.meta.json \u0434\u043B\u044F \u0434\u043E\u043A\u043E\u0432 \u0438 CLI.",
+    META_HINT_SYNC_SCHEMA: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430: \u0434\u043E\u0431\u0430\u0432\u044C\u0442\u0435 \u0438\u0445 \u0432 Zod-\u0441\u0445\u0435\u043C\u0443 \u0438\u043B\u0438 \u0443\u0434\u0430\u043B\u0438\u0442\u0435 \u0438\u0437 env.meta.json."
   }
 };
 
@@ -148,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");
@@ -163,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"
   ]);
 }
 
@@ -226,7 +245,7 @@ function generateEnvExample(meta) {
 function buildRows(entries) {
   return entries.map(([key, m]) => {
     const req = m.required === false ? "no" : "yes";
-    const dep = m.deprecated ? "\u26A0\uFE0F" : "";
+    const dep = m.deprecated === true ? "\u26A0\uFE0F" : typeof m.deprecated === "string" ? `\u26A0\uFE0F ${m.deprecated}` : "";
     const link = m.link ? m.link : "";
     return {
       Key: key,
@@ -422,16 +441,25 @@ function getUnknownEnv(meta, env = process.env) {
   return unknown;
 }
 var SECRET_PATTERNS = [
-  (k) => k.includes("TOKEN"),
   (k) => k.includes("SECRET"),
   (k) => k.includes("PASSWORD"),
+  (k) => k.includes("PASS"),
+  (k) => k.includes("PWD"),
   (k) => k.includes("PRIVATE"),
   (k) => k.includes("API_KEY"),
-  (k) => k.endsWith("_KEY")
+  (k) => k.endsWith("_KEY"),
+  (k) => k === "KEY",
+  (k) => k === "API",
+  (k) => k.includes("TOKEN"),
+  (k) => k.includes("JWT"),
+  (k) => k.includes("SESSION"),
+  (k) => k.includes("CREDENTIAL"),
+  (k) => k.includes("CREDS"),
+  (k) => k.includes("DATABASE_URL") || k === "DB_URL",
+  (k) => k.includes("CONNECTION_STRING")
 ];
 function isSecretKey(key) {
-  const k = key.toUpperCase();
-  return SECRET_PATTERNS.some((fn) => fn(k));
+  return SECRET_PATTERNS.some((fn) => fn(key.toUpperCase()));
 }
 
 // src/cli/lib/mask.ts
@@ -554,20 +582,96 @@ function registerShow(program2, getLang2) {
   });
 }
 
+// src/cli/lib/schema.ts
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_module = require("module");
+var import_node_url = require("url");
+var require2 = (0, import_node_module.createRequire)(import_node_path3.default.join(process.cwd(), "package.json"));
+async function loadSchemaFile(filePath, lang) {
+  const absolutePath = import_node_path3.default.isAbsolute(filePath) ? filePath : import_node_path3.default.resolve(process.cwd(), filePath);
+  let mod;
+  try {
+    const url = (0, import_node_url.pathToFileURL)(absolutePath).href;
+    mod = await import(url);
+  } catch {
+    try {
+      mod = require2(absolutePath);
+    } catch (e) {
+      fail(lang, "SCHEMA_LOAD_FAILED", [`- ${absolutePath}`, String(e)]);
+    }
+  }
+  const raw = mod != null && typeof mod === "object" ? mod.default ?? mod : void 0;
+  const schema = raw != null && typeof raw === "object" ? raw.default ?? raw.schema ?? raw : void 0;
+  if (schema == null) {
+    fail(lang, "SCHEMA_NOT_OBJECT", [`- ${absolutePath}`]);
+  }
+  const shape = schema != null && typeof schema === "object" && "shape" in schema && typeof schema.shape === "object" ? schema.shape : void 0;
+  if (shape == null || !Object.keys(shape).length) {
+    fail(lang, "SCHEMA_NOT_OBJECT", [`- ${absolutePath}`]);
+  }
+  return { keys: Object.keys(shape) };
+}
+
 // src/cli/commands/check.ts
 function registerCheck(program2, getLang2) {
-  program2.command("check").description("Exit with code 1 if env is invalid (loads dotenv)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--dotenv <list>", "Comma-separated dotenv files (default: .env)", ".env").option("--strict", "Fail if unknown env vars are present (dotenv-only)").action((opts) => {
+  program2.command("check").description("Exit with code 1 if env is invalid (loads dotenv)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--dotenv <list>", "Comma-separated dotenv files (default: .env)", ".env").option("--strict", "Fail if unknown env vars are present (dotenv-only)").option(
+    "--schema <file>",
+    "Path to JS file exporting Zod object; run schema\u2194meta consistency check"
+  ).option(
+    "--schema-mode <mode>",
+    "Schema\u2194meta consistency: warn (report, exit 0) or strict (report, exit 1)",
+    "strict"
+  ).action(async (opts) => {
     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") {
+        fail(lang, "INVALID_FORMAT", ["--schema-mode must be warn or strict"]);
+      }
+      const { keys: schemaKeys } = await loadSchemaFile(opts.schema, lang);
+      const metaKeys = new Set(Object.keys(meta));
+      const inSchemaNotMeta = schemaKeys.filter((k) => !metaKeys.has(k));
+      const inMetaNotSchema = [...metaKeys].filter((k) => !schemaKeys.includes(k));
+      const hasMismatch = inSchemaNotMeta.length > 0 || inMetaNotSchema.length > 0;
+      if (hasMismatch) {
+        const lines = [];
+        if (inSchemaNotMeta.length) {
+          lines.push(`\u274C ${t(lang, "SCHEMA_VARS_NOT_IN_META")}`);
+          inSchemaNotMeta.forEach((k) => lines.push(`- ${k}`));
+          lines.push(`   ${t(lang, "SCHEMA_HINT_ADD_TO_META")}`);
+          lines.push("");
+        }
+        if (inMetaNotSchema.length) {
+          lines.push(`\u274C ${t(lang, "META_VARS_NOT_IN_SCHEMA")}`);
+          inMetaNotSchema.sort((a, b) => a.localeCompare(b)).forEach((k) => lines.push(`- ${k}`));
+          lines.push(`   ${t(lang, "META_HINT_SYNC_SCHEMA")}`);
+        }
+        const out = lines.join("\n");
+        if (schemaMode === "strict") {
+          console.error(out);
+          process.exit(1);
+        }
+        console.warn(out);
       }
     }
     console.log(`\u2705 ${t(lang, "ENV_OK")}`);
@@ -577,10 +681,10 @@ function registerCheck(program2, getLang2) {
 
 // src/cli/commands/init.ts
 var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 var import_dotenv5 = __toESM(require("dotenv"), 1);
 function readEnvFile(file) {
-  const abs = import_node_path3.default.resolve(process.cwd(), file);
+  const abs = import_node_path4.default.resolve(process.cwd(), file);
   if (!import_node_fs4.default.existsSync(abs)) return {};
   const raw = import_node_fs4.default.readFileSync(abs, "utf8");
   return import_dotenv5.default.parse(raw);

package/dist/cli/index.js

@@ -5,7 +5,7 @@ import {
   getMissingEnv,
   getUnknownEnv,
   isSecretKey
-} from "../chunk-RI23O6XK.js";
+} from "../chunk-J4V5ODI6.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -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,13 +23,20 @@ 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",
-    INIT_INPUT_EMPTY: "Input env file is empty or not found:"
+    INIT_INPUT_EMPTY: "Input env file is empty or not found:",
+    SCHEMA_LOAD_FAILED: "Failed to load schema file:",
+    SCHEMA_NOT_OBJECT: "Schema file must export a Zod object (z.object(...)).",
+    SCHEMA_VARS_NOT_IN_META: "Schema variables not listed in env.meta.json:",
+    META_VARS_NOT_IN_SCHEMA: "env.meta.json variables not in schema:",
+    SCHEMA_HINT_ADD_TO_META: "Hint: add these keys to env.meta.json for docs and CLI.",
+    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:",
@@ -38,11 +46,17 @@ 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",
-    INIT_INPUT_EMPTY: "\u0424\u0430\u0439\u043B \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u043F\u0443\u0441\u0442 \u0438\u043B\u0438 \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D:"
+    INIT_INPUT_EMPTY: "\u0424\u0430\u0439\u043B \u043E\u043A\u0440\u0443\u0436\u0435\u043D\u0438\u044F \u043F\u0443\u0441\u0442 \u0438\u043B\u0438 \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D:",
+    SCHEMA_LOAD_FAILED: "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u0437\u0430\u0433\u0440\u0443\u0437\u0438\u0442\u044C \u0444\u0430\u0439\u043B \u0441\u0445\u0435\u043C\u044B:",
+    SCHEMA_NOT_OBJECT: "\u0424\u0430\u0439\u043B \u0441\u0445\u0435\u043C\u044B \u0434\u043E\u043B\u0436\u0435\u043D \u044D\u043A\u0441\u043F\u043E\u0440\u0442\u0438\u0440\u043E\u0432\u0430\u0442\u044C Zod object (z.object(...)).",
+    SCHEMA_VARS_NOT_IN_META: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 \u0441\u0445\u0435\u043C\u044B \u043E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u044E\u0442 \u0432 env.meta.json:",
+    META_VARS_NOT_IN_SCHEMA: "\u041F\u0435\u0440\u0435\u043C\u0435\u043D\u043D\u044B\u0435 env.meta.json \u043E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u044E\u0442 \u0432 \u0441\u0445\u0435\u043C\u0435:",
+    SCHEMA_HINT_ADD_TO_META: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430: \u0434\u043E\u0431\u0430\u0432\u044C\u0442\u0435 \u044D\u0442\u0438 \u043A\u043B\u044E\u0447\u0438 \u0432 env.meta.json \u0434\u043B\u044F \u0434\u043E\u043A\u043E\u0432 \u0438 CLI.",
+    META_HINT_SYNC_SCHEMA: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430: \u0434\u043E\u0431\u0430\u0432\u044C\u0442\u0435 \u0438\u0445 \u0432 Zod-\u0441\u0445\u0435\u043C\u0443 \u0438\u043B\u0438 \u0443\u0434\u0430\u043B\u0438\u0442\u0435 \u0438\u0437 env.meta.json."
   }
 };
 
@@ -132,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");
@@ -147,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"
   ]);
 }
 
@@ -342,20 +361,96 @@ function registerShow(program2, getLang2) {
   });
 }
 
+// src/cli/lib/schema.ts
+import path3 from "path";
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
+var require2 = createRequire(path3.join(process.cwd(), "package.json"));
+async function loadSchemaFile(filePath, lang) {
+  const absolutePath = path3.isAbsolute(filePath) ? filePath : path3.resolve(process.cwd(), filePath);
+  let mod;
+  try {
+    const url = pathToFileURL(absolutePath).href;
+    mod = await import(url);
+  } catch {
+    try {
+      mod = require2(absolutePath);
+    } catch (e) {
+      fail(lang, "SCHEMA_LOAD_FAILED", [`- ${absolutePath}`, String(e)]);
+    }
+  }
+  const raw = mod != null && typeof mod === "object" ? mod.default ?? mod : void 0;
+  const schema = raw != null && typeof raw === "object" ? raw.default ?? raw.schema ?? raw : void 0;
+  if (schema == null) {
+    fail(lang, "SCHEMA_NOT_OBJECT", [`- ${absolutePath}`]);
+  }
+  const shape = schema != null && typeof schema === "object" && "shape" in schema && typeof schema.shape === "object" ? schema.shape : void 0;
+  if (shape == null || !Object.keys(shape).length) {
+    fail(lang, "SCHEMA_NOT_OBJECT", [`- ${absolutePath}`]);
+  }
+  return { keys: Object.keys(shape) };
+}
+
 // src/cli/commands/check.ts
 function registerCheck(program2, getLang2) {
-  program2.command("check").description("Exit with code 1 if env is invalid (loads dotenv)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--dotenv <list>", "Comma-separated dotenv files (default: .env)", ".env").option("--strict", "Fail if unknown env vars are present (dotenv-only)").action((opts) => {
+  program2.command("check").description("Exit with code 1 if env is invalid (loads dotenv)").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--dotenv <list>", "Comma-separated dotenv files (default: .env)", ".env").option("--strict", "Fail if unknown env vars are present (dotenv-only)").option(
+    "--schema <file>",
+    "Path to JS file exporting Zod object; run schema\u2194meta consistency check"
+  ).option(
+    "--schema-mode <mode>",
+    "Schema\u2194meta consistency: warn (report, exit 0) or strict (report, exit 1)",
+    "strict"
+  ).action(async (opts) => {
     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") {
+        fail(lang, "INVALID_FORMAT", ["--schema-mode must be warn or strict"]);
+      }
+      const { keys: schemaKeys } = await loadSchemaFile(opts.schema, lang);
+      const metaKeys = new Set(Object.keys(meta));
+      const inSchemaNotMeta = schemaKeys.filter((k) => !metaKeys.has(k));
+      const inMetaNotSchema = [...metaKeys].filter((k) => !schemaKeys.includes(k));
+      const hasMismatch = inSchemaNotMeta.length > 0 || inMetaNotSchema.length > 0;
+      if (hasMismatch) {
+        const lines = [];
+        if (inSchemaNotMeta.length) {
+          lines.push(`\u274C ${t(lang, "SCHEMA_VARS_NOT_IN_META")}`);
+          inSchemaNotMeta.forEach((k) => lines.push(`- ${k}`));
+          lines.push(`   ${t(lang, "SCHEMA_HINT_ADD_TO_META")}`);
+          lines.push("");
+        }
+        if (inMetaNotSchema.length) {
+          lines.push(`\u274C ${t(lang, "META_VARS_NOT_IN_SCHEMA")}`);
+          inMetaNotSchema.sort((a, b) => a.localeCompare(b)).forEach((k) => lines.push(`- ${k}`));
+          lines.push(`   ${t(lang, "META_HINT_SYNC_SCHEMA")}`);
+        }
+        const out = lines.join("\n");
+        if (schemaMode === "strict") {
+          console.error(out);
+          process.exit(1);
+        }
+        console.warn(out);
       }
     }
     console.log(`\u2705 ${t(lang, "ENV_OK")}`);
@@ -365,10 +460,10 @@ function registerCheck(program2, getLang2) {
 
 // src/cli/commands/init.ts
 import fs4 from "fs";
-import path3 from "path";
+import path4 from "path";
 import dotenv3 from "dotenv";
 function readEnvFile(file) {
-  const abs = path3.resolve(process.cwd(), file);
+  const abs = path4.resolve(process.cwd(), file);
   if (!fs4.existsSync(abs)) return {};
   const raw = fs4.readFileSync(abs, "utf8");
   return dotenv3.parse(raw);

package/dist/index.cjs

@@ -92,7 +92,7 @@ function generateEnvExample(meta) {
 function buildRows(entries) {
   return entries.map(([key, m]) => {
     const req = m.required === false ? "no" : "yes";
-    const dep = m.deprecated ? "\u26A0\uFE0F" : "";
+    const dep = m.deprecated === true ? "\u26A0\uFE0F" : typeof m.deprecated === "string" ? `\u26A0\uFE0F ${m.deprecated}` : "";
     const link = m.link ? m.link : "";
     return {
       Key: key,
@@ -217,16 +217,25 @@ function getUnknownEnv(meta, env = process.env) {
   return unknown;
 }
 var SECRET_PATTERNS = [
-  (k) => k.includes("TOKEN"),
   (k) => k.includes("SECRET"),
   (k) => k.includes("PASSWORD"),
+  (k) => k.includes("PASS"),
+  (k) => k.includes("PWD"),
   (k) => k.includes("PRIVATE"),
   (k) => k.includes("API_KEY"),
-  (k) => k.endsWith("_KEY")
+  (k) => k.endsWith("_KEY"),
+  (k) => k === "KEY",
+  (k) => k === "API",
+  (k) => k.includes("TOKEN"),
+  (k) => k.includes("JWT"),
+  (k) => k.includes("SESSION"),
+  (k) => k.includes("CREDENTIAL"),
+  (k) => k.includes("CREDS"),
+  (k) => k.includes("DATABASE_URL") || k === "DB_URL",
+  (k) => k.includes("CONNECTION_STRING")
 ];
 function isSecretKey(key) {
-  const k = key.toUpperCase();
-  return SECRET_PATTERNS.some((fn) => fn(k));
+  return SECRET_PATTERNS.some((fn) => fn(key.toUpperCase()));
 }
 function checkEnv(meta, env = process.env) {
   const missing = getMissingEnv(meta, env);
@@ -253,7 +262,8 @@ function formatZodError(err) {
     return pa.localeCompare(pb);
   }).map((issue) => {
     const path = issue.path.length ? issue.path.join(".") : "(root)";
-    return `- ${path}: ${issue.message.trim()}`;
+    const msg = issue.message.trim() || "(validation failed)";
+    return `- ${path}: ${msg}`;
   }).join("\n");
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -6,6 +6,8 @@ import { z } from 'zod';
  * This file is part of the stable public API: it powers the CLI generators,
  * and is intended to be reusable by consumers.
  *
+ * Stable in 1.2.
+ *
  * @public
  * @since 1.0.0
  */
@@ -40,10 +42,11 @@ type EnvMetaEntry = {
     default?: string;
     /**
      * Mark variable as deprecated in docs.
+     * Use `true` for a generic warning (⚠️) or a string to show an explanation (e.g. "Use FOO instead").
      *
      * @since 1.1.0
      */
-    deprecated?: boolean;
+    deprecated?: boolean | string;
     /**
      * Version when the variable was introduced (documentation only).
      *
@@ -142,6 +145,9 @@ declare function generateEnvExample(meta: EnvMeta): string;
  */
 declare function generateEnvDocs(meta: EnvMeta, opts?: GenerateDocsOptions): string;
 
+/**
+ * Env validation helpers. Stable in 1.2.
+ */
 /**
  * Result of validating an env object against {@link EnvMeta}.
  *
@@ -175,7 +181,8 @@ declare function getUnknownEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[]
 /**
  * Detect whether an env key name looks like a secret.
  *
- * Used by the CLI to mask values (TOKEN/SECRET/PASSWORD/*_KEY/PRIVATE).
+ * Used by the CLI to mask values (e.g. SECRET, PASSWORD, TOKEN, *_KEY, connection strings).
+ * Matching is case-insensitive (key is normalized to uppercase).
  *
  * @public
  * @since 1.2.0
@@ -241,6 +248,9 @@ type LoadEnvFail = {
  *   - returns `{ ok: false, error }` by default
  *   - throws `ZodError` if `opts.throwOnError === true`
  *
+ * @remarks Load dotenv (e.g. `import "dotenv/config"`) before calling so `process.env` is populated.
+ * @see {@link mustLoadEnv} — fail-fast variant that returns env directly.
+ *
  * @example
  * ```ts
  * const result = loadEnv(EnvSchema);
@@ -260,6 +270,9 @@ declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: LoadEnvOption
  *
  * Equivalent to: `loadEnv(schema, { throwOnError: true })` but returns typed env directly.
  *
+ * @remarks Load dotenv (e.g. `import "dotenv/config"`) before calling so `process.env` is populated.
+ * @see {@link loadEnv} — returns a result object instead of throwing.
+ *
  * @example
  * ```ts
  * export const env = mustLoadEnv(EnvSchema);
@@ -274,8 +287,13 @@ declare function mustLoadEnv<T extends z.ZodTypeAny>(schema: T): z.infer<T>;
 /**
  * Format `ZodError` into a human-friendly multi-line message (one issue per line).
  *
- * Output format (stable in 1.x):
- * - path: message
+ * Output format (stable in 1.x): `path: message`
+ *
+ * @example
+ * ```ts
+ * const result = loadEnv(EnvSchema);
+ * if (!result.ok) console.error(formatZodError(result.error));
+ * ```
  *
  * @public
  * @since 1.0.0

package/dist/index.d.ts

@@ -6,6 +6,8 @@ import { z } from 'zod';
  * This file is part of the stable public API: it powers the CLI generators,
  * and is intended to be reusable by consumers.
  *
+ * Stable in 1.2.
+ *
  * @public
  * @since 1.0.0
  */
@@ -40,10 +42,11 @@ type EnvMetaEntry = {
     default?: string;
     /**
      * Mark variable as deprecated in docs.
+     * Use `true` for a generic warning (⚠️) or a string to show an explanation (e.g. "Use FOO instead").
      *
      * @since 1.1.0
      */
-    deprecated?: boolean;
+    deprecated?: boolean | string;
     /**
      * Version when the variable was introduced (documentation only).
      *
@@ -142,6 +145,9 @@ declare function generateEnvExample(meta: EnvMeta): string;
  */
 declare function generateEnvDocs(meta: EnvMeta, opts?: GenerateDocsOptions): string;
 
+/**
+ * Env validation helpers. Stable in 1.2.
+ */
 /**
  * Result of validating an env object against {@link EnvMeta}.
  *
@@ -175,7 +181,8 @@ declare function getUnknownEnv(meta: EnvMeta, env?: NodeJS.ProcessEnv): string[]
 /**
  * Detect whether an env key name looks like a secret.
  *
- * Used by the CLI to mask values (TOKEN/SECRET/PASSWORD/*_KEY/PRIVATE).
+ * Used by the CLI to mask values (e.g. SECRET, PASSWORD, TOKEN, *_KEY, connection strings).
+ * Matching is case-insensitive (key is normalized to uppercase).
  *
  * @public
  * @since 1.2.0
@@ -241,6 +248,9 @@ type LoadEnvFail = {
  *   - returns `{ ok: false, error }` by default
  *   - throws `ZodError` if `opts.throwOnError === true`
  *
+ * @remarks Load dotenv (e.g. `import "dotenv/config"`) before calling so `process.env` is populated.
+ * @see {@link mustLoadEnv} — fail-fast variant that returns env directly.
+ *
  * @example
  * ```ts
  * const result = loadEnv(EnvSchema);
@@ -260,6 +270,9 @@ declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: LoadEnvOption
  *
  * Equivalent to: `loadEnv(schema, { throwOnError: true })` but returns typed env directly.
  *
+ * @remarks Load dotenv (e.g. `import "dotenv/config"`) before calling so `process.env` is populated.
+ * @see {@link loadEnv} — returns a result object instead of throwing.
+ *
  * @example
  * ```ts
  * export const env = mustLoadEnv(EnvSchema);
@@ -274,8 +287,13 @@ declare function mustLoadEnv<T extends z.ZodTypeAny>(schema: T): z.infer<T>;
 /**
  * Format `ZodError` into a human-friendly multi-line message (one issue per line).
  *
- * Output format (stable in 1.x):
- * - path: message
+ * Output format (stable in 1.x): `path: message`
+ *
+ * @example
+ * ```ts
+ * const result = loadEnv(EnvSchema);
+ * if (!result.ok) console.error(formatZodError(result.error));
+ * ```
  *
  * @public
  * @since 1.0.0

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   getUnknownEnv,
   isSecretKey,
   sortMetaEntries
-} from "./chunk-RI23O6XK.js";
+} from "./chunk-J4V5ODI6.js";
 
 // src/index.ts
 function loadEnv(schema, opts) {
@@ -27,7 +27,8 @@ function formatZodError(err) {
     return pa.localeCompare(pb);
   }).map((issue) => {
     const path = issue.path.length ? issue.path.join(".") : "(root)";
-    return `- ${path}: ${issue.message.trim()}`;
+    const msg = issue.message.trim() || "(validation failed)";
+    return `- ${path}: ${msg}`;
   }).join("\n");
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-envkit",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "Validate environment variables with Zod and generate .env.example",
   "license": "MIT",
   "author": "",
@@ -53,8 +53,9 @@
     "ci:all": "pnpm ci:smoke && pnpm test && pnpm ci:docs",
     "prepublishOnly": "pnpm build && pnpm test",
     "docs:api": "typedoc --tsconfig tsconfig.docs.json --entryPoints src/index.ts",
-    "docs:build": "pnpm docs:api && vitepress build docs",
-    "docs:dev": "vitepress dev docs",
+    "docs:build": "pnpm docs:api && node scripts/copy-changelog-to-docs.cjs && vitepress build docs",
+    "docs:dev": "node scripts/copy-changelog-to-docs.cjs && vitepress dev docs",
+    "docs:links": "find docs -name '*.md' -not -path '*/.vitepress/*' -exec pnpm exec markdown-link-check -c docs/.markdown-link-check.json {} \\;",
     "release": "semantic-release"
   },
   "dependencies": {
@@ -72,6 +73,7 @@
     "@types/node": "^25.0.10",
     "eslint": "^9.39.2",
     "execa": "^9.6.1",
+    "markdown-link-check": "3.10.0",
     "semantic-release": "^22.0.12",
     "tmp-promise": "^3.0.3",
     "tsup": "^8.5.1",