zod-envkit 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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)
 
 

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:",
@@ -47,6 +49,8 @@ var messages = {
     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:",
@@ -59,6 +63,9 @@ var messages = {
 };
 
 // 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 +76,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 +103,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 +127,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
@@ -345,12 +374,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 +393,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);
@@ -479,12 +511,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`);
@@ -540,12 +578,12 @@ 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_dotenv5 = __toESM(require("dotenv"), 1);
 function readEnvFile(file) {
   const abs = import_node_path3.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

@@ -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:",
@@ -31,6 +33,8 @@ var messages = {
     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:",
@@ -43,6 +47,9 @@ var messages = {
 };
 
 // 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 +60,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 +87,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 +111,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 +195,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 +214,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 +299,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`);
@@ -328,12 +366,12 @@ function registerCheck(program2, getLang2) {
 // src/cli/commands/init.ts
 import fs4 from "fs";
 import path3 from "path";
-import dotenv2 from "dotenv";
+import dotenv3 from "dotenv";
 function readEnvFile(file) {
   const abs = path3.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

@@ -247,7 +247,14 @@ 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)";
+    return `- ${path}: ${issue.message.trim()}`;
+  }).join("\n");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -274,10 +274,8 @@ 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).
  *
- * @example
- * ```ts
- * console.error("Invalid environment:\n" + formatZodError(err));
- * ```
+ * Output format (stable in 1.x):
+ * - path: message
  *
  * @public
  * @since 1.0.0

package/dist/index.d.ts

@@ -274,10 +274,8 @@ 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).
  *
- * @example
- * ```ts
- * console.error("Invalid environment:\n" + formatZodError(err));
- * ```
+ * Output format (stable in 1.x):
+ * - path: message
  *
  * @public
  * @since 1.0.0

package/dist/index.js

@@ -21,7 +21,14 @@ 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)";
+    return `- ${path}: ${issue.message.trim()}`;
+  }).join("\n");
 }
 export {
   checkEnv,

package/package.json

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