zod-envkit 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* reliability polish (meta fallback, strict isolation, deterministic errors) ([a439230](https://github.com/nxtxe/zod-envkit/commit/a439230ccd06f7c7dbd70963cdfe33ed9fae9c57))
+
 ## [1.2.2](https://github.com/nxtxe/zod-envkit/compare/v1.2.1...v1.2.2) (2026-02-16)
 
 
@@ -13,10 +27,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
 
@@ -216,3 +226,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

@@ -33,6 +33,8 @@ var messages = {
     META_TRIED: "Tried:",
     META_TIP: "Tip:",
     META_PARSE_FAILED: "Failed to read/parse env meta file:",
+    META_FALLBACK_EXAMPLE: "env.meta.json not found, falling back to .env.example (minimal meta).",
+    META_FALLBACK_TIP: "Tip: create env.meta.json for richer docs, grouping, and stable CLI behavior.",
     GENERATED: "Generated: {example}, {docs}",
     ENV_OK: "Environment looks good.",
     MISSING_ENV: "Missing required environment variables:",
@@ -40,13 +42,21 @@ var messages = {
     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: {
     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:",
     META_PARSE_FAILED: "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u043F\u0440\u043E\u0447\u0438\u0442\u0430\u0442\u044C \u0438\u043B\u0438 \u0440\u0430\u0441\u043F\u0430\u0440\u0441\u0438\u0442\u044C env meta \u0444\u0430\u0439\u043B:",
+    META_FALLBACK_EXAMPLE: "env.meta.json \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D, \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u0443\u0435\u043C .env.example \u043A\u0430\u043A \u043C\u0438\u043D\u0438\u043C\u0430\u043B\u044C\u043D\u0443\u044E \u043C\u0435\u0442\u0443.",
+    META_FALLBACK_TIP: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430: \u043B\u0443\u0447\u0448\u0435 \u0441\u043E\u0437\u0434\u0430\u0442\u044C env.meta.json \u2014 \u0431\u0443\u0434\u0435\u0442 \u0431\u043E\u0433\u0430\u0447\u0435 \u0434\u043E\u043A\u0443\u043C\u0435\u043D\u0442\u0430\u0446\u0438\u044F \u0438 \u0441\u0442\u0430\u0431\u0438\u043B\u044C\u043D\u0435\u0435 CLI-\u043A\u043E\u043D\u0442\u0440\u0430\u043A\u0442.",
     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:",
@@ -54,11 +64,20 @@ var messages = {
     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."
   }
 };
 
 // src/i18n.ts
+function escapeRegExp(source) {
+  return source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function resolveLang(cliLang) {
   if (cliLang === "ru" || cliLang === "en") return cliLang;
   const envLang = process.env.LANG?.toLowerCase();
@@ -69,7 +88,8 @@ 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);
+      const pattern = new RegExp(`\\{${escapeRegExp(k)}\\}`, "g");
+      text = text.replace(pattern, v);
     }
   }
   return text;
@@ -95,6 +115,7 @@ var import_node_fs2 = __toESM(require("fs"), 1);
 // src/cli/lib/meta.ts
 var import_node_fs = __toESM(require("fs"), 1);
 var import_node_path = __toESM(require("path"), 1);
+var import_dotenv = __toESM(require("dotenv"), 1);
 
 // src/cli/lib/fail.ts
 function fail(lang, key, details) {
@@ -118,24 +139,44 @@ function resolveMetaPath(configFile) {
   const found = candidates.find((p) => import_node_fs.default.existsSync(p));
   return { candidates, found };
 }
+function buildMetaFromEnvExample(examplePath) {
+  const raw = import_node_fs.default.readFileSync(examplePath, "utf8");
+  const parsed = import_dotenv.default.parse(raw);
+  const meta = {};
+  const keys = Object.keys(parsed).sort((a, b) => a.localeCompare(b));
+  for (const key of keys) {
+    meta[key] = {
+      example: parsed[key] ?? "",
+      required: true,
+      description: ""
+    };
+  }
+  return meta;
+}
 function loadMeta(lang, configFile) {
   const { candidates, found } = resolveMetaPath(configFile);
-  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"
-    ]);
+  if (found) {
+    try {
+      const raw = import_node_fs.default.readFileSync(found, "utf8");
+      return { meta: JSON.parse(raw), configPath: found };
+    } catch {
+      fail(lang, "META_PARSE_FAILED", [`- ${found}`]);
+    }
   }
-  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 examplePath = import_node_path.default.resolve(process.cwd(), ".env.example");
+  if (import_node_fs.default.existsSync(examplePath)) {
+    console.warn(`\u26A0\uFE0F ${t(lang, "META_FALLBACK_EXAMPLE")}`);
+    console.warn(`   ${t(lang, "META_FALLBACK_TIP")}`);
+    console.warn("");
+    return { meta: buildMetaFromEnvExample(examplePath), configPath: examplePath };
   }
+  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"
+  ]);
 }
 
 // src/generate.ts
@@ -197,7 +238,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,
@@ -345,12 +386,15 @@ function registerGenerate(program2, getLang2) {
 // src/cli/lib/dotenv.ts
 var import_node_fs3 = __toESM(require("fs"), 1);
 var import_node_path2 = __toESM(require("path"), 1);
-var import_dotenv = __toESM(require("dotenv"), 1);
+var import_dotenv2 = __toESM(require("dotenv"), 1);
 function resolvePath(p) {
   return import_node_path2.default.resolve(process.cwd(), p);
 }
 function loadDotEnv(files) {
-  const list = files?.split(",").map((s) => s.trim()).filter(Boolean) ?? [".env"];
+  let list = files?.split(",").map((s) => s.trim()).filter(Boolean) ?? [".env"];
+  if (list.length === 0) {
+    list = [".env"];
+  }
   const loaded = [];
   const skipped = [];
   const merged = {};
@@ -361,7 +405,7 @@ function loadDotEnv(files) {
       continue;
     }
     const raw = import_node_fs3.default.readFileSync(abs, "utf8");
-    const parsed = import_dotenv.default.parse(raw);
+    const parsed = import_dotenv2.default.parse(raw);
     for (const [k, v] of Object.entries(parsed)) merged[k] = v;
     for (const [k, v] of Object.entries(parsed)) process.env[k] = v;
     loaded.push(f);
@@ -390,16 +434,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
@@ -479,12 +532,18 @@ function isSortMode2(v) {
   return v === "alpha" || v === "required-first" || v === "none";
 }
 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) => {
+  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)").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, String(opts.config ?? "env.meta.json"));
-    const fallbackMode = opts.mask === false ? "none" : "partial";
-    const modeRaw = String(opts.maskMode ?? fallbackMode);
+    let modeRaw;
+    if (opts.mask === false) {
+      modeRaw = "none";
+    } else if (opts.maskMode) {
+      modeRaw = String(opts.maskMode);
+    } else {
+      modeRaw = "partial";
+    }
     if (!isMaskMode(modeRaw)) {
       console.error(`\u274C ${t(lang, "INVALID_MASK_MODE")}: ${modeRaw}`);
       console.error(`- partial | full | none`);
@@ -516,9 +575,46 @@ 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);
@@ -532,6 +628,37 @@ function registerCheck(program2, getLang2) {
         fail(lang, "UNKNOWN_ENV", unknown.map((k) => `- ${k}`));
       }
     }
+    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")}`);
     process.exit(0);
   });
@@ -539,13 +666,13 @@ 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_dotenv4 = __toESM(require("dotenv"), 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_dotenv4.default.parse(raw);
+  return import_dotenv5.default.parse(raw);
 }
 function metaFromEnv(env, defaultGroup) {
   const meta = {};

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";
@@ -17,6 +17,8 @@ var messages = {
     META_TRIED: "Tried:",
     META_TIP: "Tip:",
     META_PARSE_FAILED: "Failed to read/parse env meta file:",
+    META_FALLBACK_EXAMPLE: "env.meta.json not found, falling back to .env.example (minimal meta).",
+    META_FALLBACK_TIP: "Tip: create env.meta.json for richer docs, grouping, and stable CLI behavior.",
     GENERATED: "Generated: {example}, {docs}",
     ENV_OK: "Environment looks good.",
     MISSING_ENV: "Missing required environment variables:",
@@ -24,13 +26,21 @@ var messages = {
     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: {
     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:",
     META_PARSE_FAILED: "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u043F\u0440\u043E\u0447\u0438\u0442\u0430\u0442\u044C \u0438\u043B\u0438 \u0440\u0430\u0441\u043F\u0430\u0440\u0441\u0438\u0442\u044C env meta \u0444\u0430\u0439\u043B:",
+    META_FALLBACK_EXAMPLE: "env.meta.json \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D, \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u0443\u0435\u043C .env.example \u043A\u0430\u043A \u043C\u0438\u043D\u0438\u043C\u0430\u043B\u044C\u043D\u0443\u044E \u043C\u0435\u0442\u0443.",
+    META_FALLBACK_TIP: "\u041F\u043E\u0434\u0441\u043A\u0430\u0437\u043A\u0430: \u043B\u0443\u0447\u0448\u0435 \u0441\u043E\u0437\u0434\u0430\u0442\u044C env.meta.json \u2014 \u0431\u0443\u0434\u0435\u0442 \u0431\u043E\u0433\u0430\u0447\u0435 \u0434\u043E\u043A\u0443\u043C\u0435\u043D\u0442\u0430\u0446\u0438\u044F \u0438 \u0441\u0442\u0430\u0431\u0438\u043B\u044C\u043D\u0435\u0435 CLI-\u043A\u043E\u043D\u0442\u0440\u0430\u043A\u0442.",
     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:",
@@ -38,11 +48,20 @@ var messages = {
     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."
   }
 };
 
 // src/i18n.ts
+function escapeRegExp(source) {
+  return source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function resolveLang(cliLang) {
   if (cliLang === "ru" || cliLang === "en") return cliLang;
   const envLang = process.env.LANG?.toLowerCase();
@@ -53,7 +72,8 @@ 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);
+      const pattern = new RegExp(`\\{${escapeRegExp(k)}\\}`, "g");
+      text = text.replace(pattern, v);
     }
   }
   return text;
@@ -79,6 +99,7 @@ import fs2 from "fs";
 // src/cli/lib/meta.ts
 import fs from "fs";
 import path from "path";
+import dotenv from "dotenv";
 
 // src/cli/lib/fail.ts
 function fail(lang, key, details) {
@@ -102,24 +123,44 @@ function resolveMetaPath(configFile) {
   const found = candidates.find((p) => fs.existsSync(p));
   return { candidates, found };
 }
+function buildMetaFromEnvExample(examplePath) {
+  const raw = fs.readFileSync(examplePath, "utf8");
+  const parsed = dotenv.parse(raw);
+  const meta = {};
+  const keys = Object.keys(parsed).sort((a, b) => a.localeCompare(b));
+  for (const key of keys) {
+    meta[key] = {
+      example: parsed[key] ?? "",
+      required: true,
+      description: ""
+    };
+  }
+  return meta;
+}
 function loadMeta(lang, configFile) {
   const { candidates, found } = resolveMetaPath(configFile);
-  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"
-    ]);
+  if (found) {
+    try {
+      const raw = fs.readFileSync(found, "utf8");
+      return { meta: JSON.parse(raw), configPath: found };
+    } catch {
+      fail(lang, "META_PARSE_FAILED", [`- ${found}`]);
+    }
   }
-  const configPath = found;
-  try {
-    const raw = fs.readFileSync(configPath, "utf8");
-    return { meta: JSON.parse(raw), configPath };
-  } catch {
-    fail(lang, "META_PARSE_FAILED", [`- ${configPath}`]);
+  const examplePath = path.resolve(process.cwd(), ".env.example");
+  if (fs.existsSync(examplePath)) {
+    console.warn(`\u26A0\uFE0F ${t(lang, "META_FALLBACK_EXAMPLE")}`);
+    console.warn(`   ${t(lang, "META_FALLBACK_TIP")}`);
+    console.warn("");
+    return { meta: buildMetaFromEnvExample(examplePath), configPath: examplePath };
   }
+  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"
+  ]);
 }
 
 // src/cli/commands/generate.ts
@@ -166,12 +207,15 @@ function registerGenerate(program2, getLang2) {
 // src/cli/lib/dotenv.ts
 import fs3 from "fs";
 import path2 from "path";
-import dotenv from "dotenv";
+import dotenv2 from "dotenv";
 function resolvePath(p) {
   return path2.resolve(process.cwd(), p);
 }
 function loadDotEnv(files) {
-  const list = files?.split(",").map((s) => s.trim()).filter(Boolean) ?? [".env"];
+  let list = files?.split(",").map((s) => s.trim()).filter(Boolean) ?? [".env"];
+  if (list.length === 0) {
+    list = [".env"];
+  }
   const loaded = [];
   const skipped = [];
   const merged = {};
@@ -182,7 +226,7 @@ function loadDotEnv(files) {
       continue;
     }
     const raw = fs3.readFileSync(abs, "utf8");
-    const parsed = dotenv.parse(raw);
+    const parsed = dotenv2.parse(raw);
     for (const [k, v] of Object.entries(parsed)) merged[k] = v;
     for (const [k, v] of Object.entries(parsed)) process.env[k] = v;
     loaded.push(f);
@@ -267,12 +311,18 @@ function isSortMode2(v) {
   return v === "alpha" || v === "required-first" || v === "none";
 }
 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) => {
+  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)").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, String(opts.config ?? "env.meta.json"));
-    const fallbackMode = opts.mask === false ? "none" : "partial";
-    const modeRaw = String(opts.maskMode ?? fallbackMode);
+    let modeRaw;
+    if (opts.mask === false) {
+      modeRaw = "none";
+    } else if (opts.maskMode) {
+      modeRaw = String(opts.maskMode);
+    } else {
+      modeRaw = "partial";
+    }
     if (!isMaskMode(modeRaw)) {
       console.error(`\u274C ${t(lang, "INVALID_MASK_MODE")}: ${modeRaw}`);
       console.error(`- partial | full | none`);
@@ -304,9 +354,46 @@ 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);
@@ -320,6 +407,37 @@ function registerCheck(program2, getLang2) {
         fail(lang, "UNKNOWN_ENV", unknown.map((k) => `- ${k}`));
       }
     }
+    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")}`);
     process.exit(0);
   });
@@ -327,13 +445,13 @@ function registerCheck(program2, getLang2) {
 
 // src/cli/commands/init.ts
 import fs4 from "fs";
-import path3 from "path";
-import dotenv2 from "dotenv";
+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 dotenv2.parse(raw);
+  return dotenv3.parse(raw);
 }
 function metaFromEnv(env, defaultGroup) {
   const meta = {};

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);
@@ -247,7 +256,15 @@ function mustLoadEnv(schema) {
   throw res.error;
 }
 function formatZodError(err) {
-  return err.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+  return err.issues.slice().sort((a, b) => {
+    const pa = a.path.length ? a.path.join(".") : "";
+    const pb = b.path.length ? b.path.join(".") : "";
+    return pa.localeCompare(pb);
+  }).map((issue) => {
+    const path = issue.path.length ? issue.path.join(".") : "(root)";
+    const msg = issue.message.trim() || "(validation failed)";
+    return `- ${path}: ${msg}`;
+  }).join("\n");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

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,9 +287,12 @@ 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`
+ *
  * @example
  * ```ts
- * console.error("Invalid environment:\n" + formatZodError(err));
+ * const result = loadEnv(EnvSchema);
+ * if (!result.ok) console.error(formatZodError(result.error));
  * ```
  *
  * @public

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,9 +287,12 @@ 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`
+ *
  * @example
  * ```ts
- * console.error("Invalid environment:\n" + formatZodError(err));
+ * const result = loadEnv(EnvSchema);
+ * if (!result.ok) console.error(formatZodError(result.error));
  * ```
  *
  * @public

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) {
@@ -21,7 +21,15 @@ function mustLoadEnv(schema) {
   throw res.error;
 }
 function formatZodError(err) {
-  return err.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+  return err.issues.slice().sort((a, b) => {
+    const pa = a.path.length ? a.path.join(".") : "";
+    const pb = b.path.length ? b.path.join(".") : "";
+    return pa.localeCompare(pb);
+  }).map((issue) => {
+    const path = issue.path.length ? issue.path.join(".") : "(root)";
+    const msg = issue.message.trim() || "(validation failed)";
+    return `- ${path}: ${msg}`;
+  }).join("\n");
 }
 export {
   checkEnv,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-envkit",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "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",