@xlameiro/env-typegen 0.1.3 → 0.1.5

package/dist/cli.js

@@ -99,7 +99,7 @@ var require_picocolors = __commonJS({
 });
 
 // src/cli.ts
-import { realpathSync } from "fs";
+import { existsSync as existsSync6, realpathSync } from "fs";
 import { createRequire } from "module";
 import path13 from "path";
 import { fileURLToPath, pathToFileURL as pathToFileURL5 } from "url";
@@ -110,14 +110,27 @@ import { existsSync } from "fs";
 import path from "path";
 import { pathToFileURL } from "url";
 var CONFIG_FILE_NAMES = [
-  "env-typegen.config.ts",
   "env-typegen.config.mjs",
-  "env-typegen.config.js"
+  "env-typegen.config.js",
+  "env-typegen.config.ts"
 ];
 async function loadConfig(cwd = process.cwd()) {
   for (const name of CONFIG_FILE_NAMES) {
     const filePath = path.resolve(cwd, name);
     if (existsSync(filePath)) {
+      if (filePath.endsWith(".ts")) {
+        throw new Error(
+          `Config file "${name}" was found but TypeScript files cannot be loaded directly at runtime.
+Rename it to "env-typegen.config.mjs" and use ESM export syntax:
+
+  // env-typegen.config.mjs
+  import { defineConfig } from "@xlameiro/env-typegen";
+  export default defineConfig({ input: ".env.example" });
+
+Tip: keep env-typegen.config.ts for IDE autocompletion and create a sibling
+env-typegen.config.mjs for runtime loading.`
+        );
+      }
       const fileUrl = pathToFileURL(filePath).href;
       const mod = await import(fileUrl);
       return mod.default;
@@ -133,12 +146,13 @@ import path5 from "path";
 import path2 from "path";
 function generateDeclaration(parsed) {
   const fileName = path2.basename(parsed.filePath);
-  const lines = [];
-  lines.push("// Generated by env-typegen \u2014 do not edit manually");
-  lines.push(`// Source: ${fileName}`);
-  lines.push("");
-  lines.push("declare namespace NodeJS {");
-  lines.push("  interface ProcessEnv {");
+  const lines = [
+    "// Generated by env-typegen \u2014 do not edit manually",
+    `// Source: ${fileName}`,
+    "",
+    "declare namespace NodeJS {",
+    "  interface ProcessEnv {"
+  ];
   for (const variable of parsed.vars) {
     const effectiveType = variable.annotatedType ?? variable.inferredType;
     const optional = variable.isOptional ? "?" : "";
@@ -153,12 +167,14 @@ function generateDeclaration(parsed) {
     }
     lines.push(propLine);
   }
-  lines.push("  }");
-  lines.push("}");
+  lines.push("  }", "}");
   return lines.join("\n") + "\n";
 }
 
 // src/generators/t3-generator.ts
+function escapeJsStringLiteral(value) {
+  return value.replaceAll("\\", String.raw`\\`).replaceAll('"', String.raw`\"`);
+}
 function toT3ZodType(envVarType) {
   if (envVarType === "number") return "z.coerce.number()";
   if (envVarType === "boolean") return "z.coerce.boolean()";
@@ -166,51 +182,47 @@ function toT3ZodType(envVarType) {
   if (envVarType === "email") return "z.string().email()";
   return "z.string()";
 }
+function buildZodExpr(variable) {
+  const effectiveType = variable.annotatedType ?? variable.inferredType;
+  let zodExpr = toT3ZodType(effectiveType);
+  if (variable.description !== void 0) {
+    zodExpr += `.describe("${escapeJsStringLiteral(variable.description)}")`;
+  }
+  if (variable.isOptional) {
+    zodExpr += ".optional()";
+  }
+  return zodExpr;
+}
 function generateT3Env(parsed) {
   const serverVars = parsed.vars.filter((v) => !v.isClientSide);
   const clientVars = parsed.vars.filter((v) => v.isClientSide);
-  const lines = [];
-  lines.push("// Generated by env-typegen \u2014 do not edit manually");
-  lines.push('import { createEnv } from "@t3-oss/env-nextjs";');
-  lines.push('import { z } from "zod";');
-  lines.push("");
-  lines.push("export const env = createEnv({");
+  const lines = [
+    "// Generated by env-typegen \u2014 do not edit manually",
+    'import { createEnv } from "@t3-oss/env-nextjs";',
+    'import { z } from "zod";',
+    "",
+    "export const env = createEnv({"
+  ];
   if (serverVars.length > 0) {
-    lines.push("  server: {");
-    for (const variable of serverVars) {
-      const effectiveType = variable.annotatedType ?? variable.inferredType;
-      let zodExpr = toT3ZodType(effectiveType);
-      if (variable.description !== void 0) {
-        zodExpr += `.describe("${variable.description.replace(/"/g, '\\"')}")`;
-      }
-      if (variable.isOptional) {
-        zodExpr += ".optional()";
-      }
-      lines.push(`    ${variable.key}: ${zodExpr},`);
-    }
-    lines.push("  },");
+    lines.push(
+      "  server: {",
+      ...serverVars.map((v) => `    ${v.key}: ${buildZodExpr(v)},`),
+      "  },"
+    );
   }
   if (clientVars.length > 0) {
-    lines.push("  client: {");
-    for (const variable of clientVars) {
-      const effectiveType = variable.annotatedType ?? variable.inferredType;
-      let zodExpr = toT3ZodType(effectiveType);
-      if (variable.description !== void 0) {
-        zodExpr += `.describe("${variable.description.replace(/"/g, '\\"')}")`;
-      }
-      if (variable.isOptional) {
-        zodExpr += ".optional()";
-      }
-      lines.push(`    ${variable.key}: ${zodExpr},`);
-    }
-    lines.push("  },");
-  }
-  lines.push("  runtimeEnv: {");
-  for (const variable of parsed.vars) {
-    lines.push(`    ${variable.key}: process.env.${variable.key},`);
+    lines.push(
+      "  client: {",
+      ...clientVars.map((v) => `    ${v.key}: ${buildZodExpr(v)},`),
+      "  },"
+    );
   }
-  lines.push("  },");
-  lines.push("});");
+  lines.push(
+    "  runtimeEnv: {",
+    ...parsed.vars.map((v) => `    ${v.key}: process.env.${v.key},`),
+    "  },",
+    "});"
+  );
   return lines.join("\n") + "\n";
 }
 
@@ -227,12 +239,14 @@ function generateTypeScriptTypes(parsed) {
   const fileName = path3.basename(parsed.filePath);
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   const lines = [];
-  lines.push("// Generated by env-typegen \u2014 do not edit manually");
-  lines.push(`// Source: ${fileName}`);
-  lines.push(`// Generated at: ${timestamp}`);
-  lines.push("");
-  lines.push("declare namespace NodeJS {");
-  lines.push("  interface ProcessEnv {");
+  lines.push(
+    "// Generated by env-typegen \u2014 do not edit manually",
+    `// Source: ${fileName}`,
+    `// Generated at: ${timestamp}`,
+    "",
+    "declare namespace NodeJS {",
+    "  interface ProcessEnv {"
+  );
   for (const variable of parsed.vars) {
     const effectiveType = variable.annotatedType ?? variable.inferredType;
     const optional = variable.isOptional ? "?" : "";
@@ -247,10 +261,7 @@ function generateTypeScriptTypes(parsed) {
     }
     lines.push(propLine);
   }
-  lines.push("  }");
-  lines.push("}");
-  lines.push("");
-  lines.push("export type EnvVars = {");
+  lines.push("  }", "}", "", "export type EnvVars = {");
   for (const variable of parsed.vars) {
     const effectiveType = variable.annotatedType ?? variable.inferredType;
     const tsType = toTsType(effectiveType);
@@ -260,9 +271,11 @@ function generateTypeScriptTypes(parsed) {
   lines.push("};");
   if (hasClientVars) {
     const clientKeyUnion = clientVars.map((v) => `"${v.key}"`).join(" | ");
-    lines.push("");
-    lines.push(`export type ServerEnvVars = Omit<EnvVars, ${clientKeyUnion}>;`);
-    lines.push(`export type ClientEnvVars = Pick<EnvVars, ${clientKeyUnion}>;`);
+    lines.push(
+      "",
+      `export type ServerEnvVars = Omit<EnvVars, ${clientKeyUnion}>;`,
+      `export type ClientEnvVars = Pick<EnvVars, ${clientKeyUnion}>;`
+    );
   }
   return lines.join("\n") + "\n";
 }
@@ -279,27 +292,29 @@ function generateZodSchema(parsed) {
   const serverVars = parsed.vars.filter((v) => !v.isClientSide);
   const clientVars = parsed.vars.filter((v) => v.isClientSide);
   const lines = [];
-  lines.push("// Generated by env-typegen \u2014 do not edit manually");
-  lines.push('import { z } from "zod";');
-  lines.push("");
-  lines.push("export const serverEnvSchema = z.object({");
+  lines.push(
+    "// Generated by env-typegen \u2014 do not edit manually",
+    'import { z } from "zod";',
+    "",
+    "export const serverEnvSchema = z.object({"
+  );
   for (const variable of serverVars) {
     const effectiveType = variable.annotatedType ?? variable.inferredType;
     const zodExpr = variable.isOptional ? `${toZodType(effectiveType)}.optional()` : toZodType(effectiveType);
     lines.push(`  ${variable.key}: ${zodExpr},`);
   }
-  lines.push("});");
-  lines.push("");
-  lines.push("export const clientEnvSchema = z.object({");
+  lines.push("});", "", "export const clientEnvSchema = z.object({");
   for (const variable of clientVars) {
     const effectiveType = variable.annotatedType ?? variable.inferredType;
     const zodExpr = variable.isOptional ? `${toZodType(effectiveType)}.optional()` : toZodType(effectiveType);
     lines.push(`  ${variable.key}: ${zodExpr},`);
   }
-  lines.push("});");
-  lines.push("");
-  lines.push("export const envSchema = serverEnvSchema.merge(clientEnvSchema);");
-  lines.push("export type Env = z.infer<typeof envSchema>;");
+  lines.push(
+    "});",
+    "",
+    "export const envSchema = serverEnvSchema.merge(clientEnvSchema);",
+    "export type Env = z.infer<typeof envSchema>;"
+  );
   return lines.join("\n") + "\n";
 }
 
@@ -359,7 +374,9 @@ var inferenceRules = [
   {
     id: "P8_numeric_literal",
     priority: 8,
-    match: (_key, value) => /^\d+(\.\d+)?$/.test(value),
+    // Non-capturing group with \d keeps the dot/digit boundary unambiguous,
+    // eliminating super-linear backtracking (ReDoS-safe).
+    match: (_key, value) => /^\d+(?:\.\d+)?$/.test(value),
     type: "number"
   },
   {
@@ -377,7 +394,9 @@ var inferenceRules = [
   {
     id: "P11_email_literal",
     priority: 11,
-    match: (_key, value) => /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value),
+    // Dots are excluded from each domain-segment character class so that the
+    // literal \. separators are unambiguous, preventing super-linear backtracking.
+    match: (_key, value) => /^[^@\s]+@[^@\s.]+(?:\.[^@\s.]+)+$/.test(value),
     type: "email"
   },
   {
@@ -494,7 +513,50 @@ function parseCommentBlock(lines) {
 
 // src/parser/env-parser.ts
 var ENV_VAR_RE = /^([A-Z_][A-Z0-9_]*)=(.*)$/;
-var SECTION_HEADER_RE = /^#\s+[-=]{3,}\s+(.+?)\s+[-=]{3,}\s*$/;
+var SECTION_HEADER_RE = /^#\s+[-=]{3,}\s+(\S+(?:\s+\S+)*)\s+[-=]{3,}\s*$/;
+function buildParsedVar(params, commentBlock, options) {
+  const annotations = parseCommentBlock(commentBlock);
+  const extraRules = options?.inferenceRules;
+  const inferredType = inferType(
+    params.key,
+    params.rawValue,
+    ...extraRules === void 0 ? [] : [{ extraRules }]
+  );
+  const isRequired = params.rawValue.length > 0 || annotations.isRequired;
+  const isOptional = params.rawValue.length === 0 && !annotations.isRequired;
+  const isClientSide = params.key.startsWith("NEXT_PUBLIC_");
+  const parsedVar = {
+    key: params.key,
+    rawValue: params.rawValue,
+    inferredType,
+    isRequired,
+    isOptional,
+    isClientSide,
+    lineNumber: params.lineNumber
+  };
+  if (annotations.annotatedType !== void 0) {
+    parsedVar.annotatedType = annotations.annotatedType;
+  }
+  if (annotations.description !== void 0) {
+    parsedVar.description = annotations.description;
+  }
+  if (params.currentGroup !== void 0) {
+    parsedVar.group = params.currentGroup;
+  }
+  if (annotations.enumValues !== void 0) {
+    parsedVar.enumValues = annotations.enumValues;
+  }
+  if (annotations.constraints !== void 0) {
+    parsedVar.constraints = annotations.constraints;
+  }
+  if (annotations.runtime !== void 0) {
+    parsedVar.runtime = annotations.runtime;
+  }
+  if (annotations.isSecret !== void 0) {
+    parsedVar.isSecret = annotations.isSecret;
+  }
+  return parsedVar;
+}
 function parseEnvFileContent(content, filePath, options) {
   const lines = content.split("\n");
   const vars = [];
@@ -524,53 +586,18 @@ function parseEnvFileContent(content, filePath, options) {
       continue;
     }
     const envMatch = ENV_VAR_RE.exec(trimmed);
-    if (envMatch !== null) {
-      const key = envMatch[1] ?? "";
-      const rawValue = envMatch[2] ?? "";
-      const annotations = parseCommentBlock(commentBlock);
-      const inferredType = inferType(
-        key,
-        rawValue,
-        ...options?.inferenceRules !== void 0 ? [{ extraRules: options.inferenceRules }] : []
-      );
-      const isRequired = rawValue.length > 0 || annotations.isRequired;
-      const isOptional = rawValue.length === 0 && !annotations.isRequired;
-      const isClientSide = key.startsWith("NEXT_PUBLIC_");
-      const parsedVar = {
-        key,
-        rawValue,
-        inferredType,
-        isRequired,
-        isOptional,
-        isClientSide,
-        lineNumber
-      };
-      if (annotations.annotatedType !== void 0) {
-        parsedVar.annotatedType = annotations.annotatedType;
-      }
-      if (annotations.description !== void 0) {
-        parsedVar.description = annotations.description;
-      }
-      if (currentGroup !== void 0) {
-        parsedVar.group = currentGroup;
-      }
-      if (annotations.enumValues !== void 0) {
-        parsedVar.enumValues = annotations.enumValues;
-      }
-      if (annotations.constraints !== void 0) {
-        parsedVar.constraints = annotations.constraints;
-      }
-      if (annotations.runtime !== void 0) {
-        parsedVar.runtime = annotations.runtime;
-      }
-      if (annotations.isSecret !== void 0) {
-        parsedVar.isSecret = annotations.isSecret;
-      }
-      vars.push(parsedVar);
-      commentBlock = [];
-    } else {
+    if (envMatch === null) {
       commentBlock = [];
+      continue;
     }
+    vars.push(
+      buildParsedVar(
+        { key: envMatch[1] ?? "", rawValue: envMatch[2] ?? "", lineNumber, currentGroup },
+        commentBlock,
+        options
+      )
+    );
+    commentBlock = [];
   }
   return { filePath, vars, groups };
 }
@@ -583,7 +610,15 @@ function parseEnvFile(filePath) {
 import { mkdir, readFile, writeFile } from "fs/promises";
 import path4 from "path";
 async function readEnvFile(filePath) {
-  return readFile(path4.resolve(filePath), "utf8");
+  const resolved = path4.resolve(filePath);
+  try {
+    return await readFile(resolved, "utf8");
+  } catch (err) {
+    if (err instanceof Error && err.code === "ENOENT") {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    throw err;
+  }
 }
 async function writeOutput(filePath, content) {
   const resolved = path4.resolve(filePath);
@@ -607,14 +642,15 @@ async function formatOutput(content, parser = "typescript") {
 
 // src/utils/logger.ts
 var import_picocolors = __toESM(require_picocolors(), 1);
+var { green, red, yellow } = import_picocolors.default;
 function log(message) {
   console.log(message);
 }
 function error(message) {
-  console.error((0, import_picocolors.red)(`\u2716 ${message}`));
+  console.error(red(`\u2716 ${message}`));
 }
 function success(message) {
-  console.log((0, import_picocolors.green)(`\u2714 ${message}`));
+  console.log(green(`\u2714 ${message}`));
 }
 
 // src/pipeline.ts
@@ -657,10 +693,6 @@ async function persistOutput(params) {
   }
   if (dryRun) {
     if (!silent) {
-      if (!isSingle) {
-        console.log(`// --- ${generator}: ${outputPath} ---`);
-      }
-      console.log(generated);
       success(`Dry run: would write ${outputPath}`);
     }
     return;
@@ -690,7 +722,7 @@ async function runGenerate(options) {
     const parsed = parseEnvFileContent(
       content,
       inputPath,
-      inferenceRules2 !== void 0 ? { inferenceRules: inferenceRules2 } : void 0
+      inferenceRules2 === void 0 ? void 0 : { inferenceRules: inferenceRules2 }
     );
     for (const generator of generators) {
       let generated = buildOutput(generator, parsed);
@@ -712,6 +744,7 @@ async function runGenerate(options) {
 }
 
 // src/validation-command.ts
+import { existsSync as existsSync4 } from "fs";
 import path11 from "path";
 import { pathToFileURL as pathToFileURL4 } from "url";
 import { parseArgs } from "util";
@@ -729,8 +762,13 @@ function readEntryValue(entry, keys) {
   }
   return void 0;
 }
+function getVercelEntries(value) {
+  if (Array.isArray(value)) return value;
+  if (isRecord(value) && Array.isArray(value.envs)) return value.envs;
+  return [];
+}
 function parseVercelPayload(value) {
-  const entries = Array.isArray(value) ? value : isRecord(value) && Array.isArray(value.envs) ? value.envs : [];
+  const entries = getVercelEntries(value);
   const result = {};
   for (const entry of entries) {
     if (!isRecord(entry)) continue;
@@ -741,8 +779,13 @@ function parseVercelPayload(value) {
   }
   return result;
 }
+function getCloudflareEntries(value) {
+  if (Array.isArray(value)) return value;
+  if (isRecord(value) && Array.isArray(value.result)) return value.result;
+  return [];
+}
 function parseCloudflarePayload(value) {
-  const entries = Array.isArray(value) ? value : isRecord(value) && Array.isArray(value.result) ? value.result : [];
+  const entries = getCloudflareEntries(value);
   const result = {};
   for (const entry of entries) {
     if (!isRecord(entry)) continue;
@@ -760,7 +803,7 @@ function parseAwsPayload(value) {
     if (!isRecord(entry)) continue;
     const name = readEntryValue(entry, ["Name", "name"]);
     if (name === void 0) continue;
-    const key = name.split("/").filter((part) => part.length > 0).pop() ?? name;
+    const key = name.split("/").findLast((part) => part.length > 0) ?? name;
     const envValue = readEntryValue(entry, ["Value", "value"]) ?? "";
     result[key] = envValue;
   }
@@ -773,7 +816,15 @@ function parseProviderPayload(provider, value) {
 }
 async function loadCloudSource(options) {
   const resolvedPath = path6.resolve(options.filePath);
-  const raw = await readFile2(resolvedPath, "utf8");
+  let raw;
+  try {
+    raw = await readFile2(resolvedPath, "utf8");
+  } catch (err) {
+    if (err instanceof Error && err.code === "ENOENT") {
+      throw new Error(`File not found: ${options.filePath}`);
+    }
+    throw err;
+  }
   const parsed = JSON.parse(raw);
   return parseProviderPayload(options.provider, parsed);
 }
@@ -905,7 +956,7 @@ function findDefaultContractPath(cwd) {
 async function loadValidationContract(options) {
   const { fallbackExamplePath, contractPath, cwd = process.cwd() } = options;
   const discoveredContractPath = findDefaultContractPath(cwd);
-  const resolvedContractPath = contractPath !== void 0 ? path7.resolve(cwd, contractPath) : discoveredContractPath;
+  const resolvedContractPath = contractPath === void 0 ? discoveredContractPath : path7.resolve(cwd, contractPath);
   if (resolvedContractPath !== void 0 && existsSync2(resolvedContractPath)) {
     const moduleUrl = pathToFileURL2(resolvedContractPath).href;
     const moduleValue = await import(moduleUrl);
@@ -924,6 +975,7 @@ async function loadValidationContract(options) {
 }
 
 // src/plugins.ts
+import { existsSync as existsSync3 } from "fs";
 import path8 from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 function isRecord3(value) {
@@ -945,10 +997,20 @@ function isPlugin(value) {
 }
 async function loadPluginFromPath(pluginPath, cwd) {
   const resolvedPath = path8.resolve(cwd, pluginPath);
+  if (!existsSync3(resolvedPath)) {
+    throw new Error(`Plugin not found: ${pluginPath}`);
+  }
   const moduleValue = await import(pathToFileURL3(resolvedPath).href);
   const candidate = moduleValue.default ?? moduleValue.plugin;
   if (isPlugin(candidate)) return candidate;
-  throw new Error(`Invalid plugin at ${resolvedPath}. Expected a plugin object export.`);
+  throw new Error(
+    `Invalid plugin at ${resolvedPath}.
+Expected a default export matching:
+  { name: string,
+    transformSource?(ctx: { environment: string; values: Record<string, string> }): Record<string, string>,
+    transformReport?(report: ValidationReport): ValidationReport,
+    transformContract?(contract: EnvContract): EnvContract }`
+  );
 }
 async function loadPlugins(options) {
   const cwd = options.cwd ?? process.cwd();
@@ -993,8 +1055,8 @@ function applyReportPlugins(report, plugins) {
 }
 
 // src/validation/engine.ts
-var EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
-var SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+var EMAIL_RE = /^[^@\s]+@[^@\s.]+(?:\.[^@\s.]+)+$/;
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
 function detectReceivedType(value) {
   const normalized = value.trim();
   if (normalized.length === 0) return "unknown";
@@ -1014,65 +1076,72 @@ function detectReceivedType(value) {
   }
   return "string";
 }
-function validateValueAgainstExpected(expected, rawValue) {
-  const normalized = rawValue.trim();
-  const receivedType = detectReceivedType(normalized);
-  if (expected.type === "unknown") return { isValid: true, receivedType };
-  if (expected.type === "string") return { isValid: true, receivedType };
-  if (expected.type === "number") {
-    const parsed = Number(normalized);
-    if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
-      return { isValid: false, receivedType, issueType: "invalid_type" };
-    }
-    if (expected.min !== void 0 && parsed < expected.min) {
-      return { isValid: false, receivedType, issueType: "invalid_value" };
-    }
-    if (expected.max !== void 0 && parsed > expected.max) {
-      return { isValid: false, receivedType, issueType: "invalid_value" };
-    }
-    return { isValid: true, receivedType };
+function validateNumber(expected, normalized, receivedType) {
+  const parsed = Number(normalized);
+  if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
+    return { isValid: false, receivedType, issueType: "invalid_type" };
   }
-  if (expected.type === "boolean") {
-    if (!["true", "false", "1", "0", "yes", "no"].includes(normalized.toLowerCase())) {
-      return { isValid: false, receivedType, issueType: "invalid_type" };
-    }
-    return { isValid: true, receivedType };
+  if (expected.min !== void 0 && parsed < expected.min) {
+    return { isValid: false, receivedType, issueType: "invalid_value" };
   }
-  if (expected.type === "enum") {
-    if (!expected.values.includes(normalized)) {
-      return { isValid: false, receivedType, issueType: "invalid_value" };
-    }
-    return { isValid: true, receivedType };
+  if (expected.max !== void 0 && parsed > expected.max) {
+    return { isValid: false, receivedType, issueType: "invalid_value" };
   }
-  if (expected.type === "url") {
-    try {
-      const value = new URL(normalized);
-      if (value.protocol.length === 0)
-        return { isValid: false, receivedType, issueType: "invalid_type" };
-      return { isValid: true, receivedType };
-    } catch {
-      return { isValid: false, receivedType, issueType: "invalid_type" };
-    }
+  return { isValid: true, receivedType };
+}
+function validateBoolean(normalized, receivedType) {
+  if (!["true", "false", "1", "0", "yes", "no"].includes(normalized.toLowerCase())) {
+    return { isValid: false, receivedType, issueType: "invalid_type" };
+  }
+  return { isValid: true, receivedType };
+}
+function validateEnum(expected, normalized, receivedType) {
+  if (!expected.values.includes(normalized)) {
+    return { isValid: false, receivedType, issueType: "invalid_value" };
   }
-  if (expected.type === "email") {
-    if (!EMAIL_RE.test(normalized))
+  return { isValid: true, receivedType };
+}
+function validateUrl(normalized, receivedType) {
+  try {
+    const value = new URL(normalized);
+    if (value.protocol.length === 0)
       return { isValid: false, receivedType, issueType: "invalid_type" };
     return { isValid: true, receivedType };
+  } catch {
+    return { isValid: false, receivedType, issueType: "invalid_type" };
   }
-  if (expected.type === "json") {
-    try {
-      const parsed = JSON.parse(normalized);
-      if (typeof parsed === "object" && parsed !== null) return { isValid: true, receivedType };
-      return { isValid: false, receivedType, issueType: "invalid_type" };
-    } catch {
-      return { isValid: false, receivedType, issueType: "invalid_type" };
-    }
+}
+function validateEmail(normalized, receivedType) {
+  if (!EMAIL_RE.test(normalized))
+    return { isValid: false, receivedType, issueType: "invalid_type" };
+  return { isValid: true, receivedType };
+}
+function validateJson(normalized, receivedType) {
+  try {
+    const parsed = JSON.parse(normalized);
+    if (typeof parsed === "object" && parsed !== null) return { isValid: true, receivedType };
+    return { isValid: false, receivedType, issueType: "invalid_type" };
+  } catch {
+    return { isValid: false, receivedType, issueType: "invalid_type" };
   }
-  if (expected.type === "semver") {
-    if (!SEMVER_RE.test(normalized))
-      return { isValid: false, receivedType, issueType: "invalid_value" };
+}
+function validateSemver(normalized, receivedType) {
+  if (!SEMVER_RE.test(normalized))
+    return { isValid: false, receivedType, issueType: "invalid_value" };
+  return { isValid: true, receivedType };
+}
+function validateValueAgainstExpected(expected, rawValue) {
+  const normalized = rawValue.trim();
+  const receivedType = detectReceivedType(normalized);
+  if (expected.type === "unknown" || expected.type === "string")
     return { isValid: true, receivedType };
-  }
+  if (expected.type === "number") return validateNumber(expected, normalized, receivedType);
+  if (expected.type === "boolean") return validateBoolean(normalized, receivedType);
+  if (expected.type === "enum") return validateEnum(expected, normalized, receivedType);
+  if (expected.type === "url") return validateUrl(normalized, receivedType);
+  if (expected.type === "email") return validateEmail(normalized, receivedType);
+  if (expected.type === "json") return validateJson(normalized, receivedType);
+  if (expected.type === "semver") return validateSemver(normalized, receivedType);
   return { isValid: true, receivedType };
 }
 function toIssueCode(issueType) {
@@ -1144,57 +1213,62 @@ function buildReport(env, issues, recommendations) {
 function isClientSecret(variable, key) {
   return variable.secret === true && (variable.clientSide || key.startsWith("NEXT_PUBLIC_"));
 }
+function checkContractVariable(key, variable, context) {
+  const { options, issues } = context;
+  const value = options.values[key];
+  const hasValue = value !== void 0;
+  if (variable.required && !hasValue) {
+    issues.push(
+      createIssue({
+        type: "missing",
+        severity: "error",
+        key,
+        environment: options.environment,
+        message: `Required variable ${key} is missing.`,
+        debugValues: options.debugValues,
+        expected: variable.expected
+      })
+    );
+    return;
+  }
+  if (!hasValue) return;
+  const validation = validateValueAgainstExpected(variable.expected, value);
+  if (!validation.isValid) {
+    const message = validation.issueType === "invalid_type" ? `Variable ${key} has invalid type.` : `Variable ${key} has invalid value.`;
+    issues.push(
+      createIssue({
+        type: validation.issueType,
+        severity: "error",
+        key,
+        environment: options.environment,
+        message,
+        value,
+        debugValues: options.debugValues,
+        expected: variable.expected,
+        receivedType: validation.receivedType
+      })
+    );
+  }
+  if (isClientSecret(variable, key)) {
+    issues.push(
+      createIssue({
+        type: "secret_exposed",
+        severity: "error",
+        key,
+        environment: options.environment,
+        message: `Secret variable ${key} is marked as client-side.`,
+        value,
+        debugValues: options.debugValues,
+        expected: variable.expected
+      })
+    );
+  }
+}
 function validateAgainstContract(options) {
   const issues = [];
   const contractKeys = new Set(Object.keys(options.contract.variables));
   for (const [key, variable] of Object.entries(options.contract.variables)) {
-    const value = options.values[key];
-    const hasValue = value !== void 0 && value.trim().length > 0;
-    if (variable.required && !hasValue) {
-      issues.push(
-        createIssue({
-          type: "missing",
-          severity: "error",
-          key,
-          environment: options.environment,
-          message: `Required variable ${key} is missing.`,
-          debugValues: options.debugValues,
-          expected: variable.expected
-        })
-      );
-      continue;
-    }
-    if (!hasValue) continue;
-    const validation = validateValueAgainstExpected(variable.expected, value);
-    if (!validation.isValid) {
-      issues.push(
-        createIssue({
-          type: validation.issueType,
-          severity: "error",
-          key,
-          environment: options.environment,
-          message: validation.issueType === "invalid_type" ? `Variable ${key} has invalid type.` : `Variable ${key} has invalid value.`,
-          value,
-          debugValues: options.debugValues,
-          expected: variable.expected,
-          receivedType: validation.receivedType
-        })
-      );
-    }
-    if (isClientSecret(variable, key)) {
-      issues.push(
-        createIssue({
-          type: "secret_exposed",
-          severity: "error",
-          key,
-          environment: options.environment,
-          message: `Secret variable ${key} is marked as client-side.`,
-          value,
-          debugValues: options.debugValues,
-          expected: variable.expected
-        })
-      );
-    }
+    checkContractVariable(key, variable, { options, issues });
   }
   for (const [key, value] of Object.entries(options.values)) {
     if (contractKeys.has(key)) continue;
@@ -1222,6 +1296,97 @@ function collectUnionKeys(contract, sources) {
   }
   return union;
 }
+function diffMissingEntries(key, missing, context) {
+  const { variable, options, issues } = context;
+  for (const entry of missing) {
+    issues.push(
+      createIssue({
+        type: "missing",
+        severity: "error",
+        key,
+        environment: entry.sourceName,
+        message: `Variable ${key} is missing in ${entry.sourceName}.`,
+        debugValues: options.debugValues,
+        ...variable !== void 0 && { expected: variable.expected }
+      })
+    );
+  }
+}
+function diffTypeConflicts(key, present, context) {
+  const { variable, options, issues } = context;
+  const typeBySource = /* @__PURE__ */ new Map();
+  for (const entry of present) {
+    typeBySource.set(entry.sourceName, detectReceivedType(entry.value ?? ""));
+  }
+  if (new Set(typeBySource.values()).size <= 1) return;
+  for (const [sourceName, detectedType] of typeBySource.entries()) {
+    issues.push(
+      createIssue({
+        type: "conflict",
+        severity: "error",
+        key,
+        environment: sourceName,
+        message: `Variable ${key} has conflicting inferred type across environments.`,
+        debugValues: options.debugValues,
+        receivedType: detectedType,
+        ...options.sources[sourceName]?.[key] !== void 0 && {
+          value: options.sources[sourceName]?.[key]
+        },
+        ...variable !== void 0 && { expected: variable.expected }
+      })
+    );
+  }
+}
+function diffPresentEntry(key, entry, context) {
+  const { variable, options, issues } = context;
+  if (entry.value === void 0) return;
+  if (variable === void 0) {
+    const severity = options.strict ? "error" : "warning";
+    issues.push(
+      createIssue({
+        type: "extra",
+        severity,
+        key,
+        environment: entry.sourceName,
+        message: `Variable ${key} is not defined in the contract.`,
+        value: entry.value,
+        debugValues: options.debugValues
+      })
+    );
+    return;
+  }
+  const validation = validateValueAgainstExpected(variable.expected, entry.value);
+  if (!validation.isValid) {
+    const message = validation.issueType === "invalid_type" ? `Variable ${key} has invalid type in ${entry.sourceName}.` : `Variable ${key} has invalid value in ${entry.sourceName}.`;
+    issues.push(
+      createIssue({
+        type: validation.issueType,
+        severity: "error",
+        key,
+        environment: entry.sourceName,
+        message,
+        value: entry.value,
+        debugValues: options.debugValues,
+        expected: variable.expected,
+        receivedType: validation.receivedType
+      })
+    );
+  }
+  if (isClientSecret(variable, key)) {
+    issues.push(
+      createIssue({
+        type: "secret_exposed",
+        severity: "error",
+        key,
+        environment: entry.sourceName,
+        message: `Secret variable ${key} is marked as client-side.`,
+        value: entry.value,
+        debugValues: options.debugValues,
+        expected: variable.expected
+      })
+    );
+  }
+}
 function diffEnvironmentSources(options) {
   const issues = [];
   const sourceNames = Object.keys(options.sources);
@@ -1232,12 +1397,8 @@ function diffEnvironmentSources(options) {
       sourceName,
       value: options.sources[sourceName]?.[key]
     }));
-    const present = valuesBySource.filter(
-      (entry) => entry.value !== void 0 && entry.value !== ""
-    );
-    const missing = valuesBySource.filter(
-      (entry) => entry.value === void 0 || entry.value === ""
-    );
+    const present = valuesBySource.filter((entry) => entry.value !== void 0);
+    const missing = valuesBySource.filter((entry) => entry.value === void 0);
     if (present.length === 0 && variable?.required === true) {
       for (const entry of missing) {
         issues.push(
@@ -1254,92 +1415,13 @@ function diffEnvironmentSources(options) {
       }
       continue;
     }
+    const ctx = { variable, options, issues };
     if (present.length > 0) {
-      for (const entry of missing) {
-        issues.push(
-          createIssue({
-            type: "missing",
-            severity: "error",
-            key,
-            environment: entry.sourceName,
-            message: `Variable ${key} is missing in ${entry.sourceName}.`,
-            debugValues: options.debugValues,
-            ...variable !== void 0 && { expected: variable.expected }
-          })
-        );
-      }
+      diffMissingEntries(key, missing, ctx);
     }
-    const typeBySource = /* @__PURE__ */ new Map();
+    diffTypeConflicts(key, present, ctx);
     for (const entry of present) {
-      const detected = detectReceivedType(entry.value ?? "");
-      typeBySource.set(entry.sourceName, detected);
-    }
-    if (new Set(typeBySource.values()).size > 1) {
-      for (const [sourceName, detectedType] of typeBySource.entries()) {
-        issues.push(
-          createIssue({
-            type: "conflict",
-            severity: "error",
-            key,
-            environment: sourceName,
-            message: `Variable ${key} has conflicting inferred type across environments.`,
-            debugValues: options.debugValues,
-            receivedType: detectedType,
-            ...options.sources[sourceName]?.[key] !== void 0 && {
-              value: options.sources[sourceName]?.[key]
-            },
-            ...variable !== void 0 && { expected: variable.expected }
-          })
-        );
-      }
-    }
-    for (const entry of present) {
-      if (entry.value === void 0) continue;
-      if (variable === void 0) {
-        const severity = options.strict ? "error" : "warning";
-        issues.push(
-          createIssue({
-            type: "extra",
-            severity,
-            key,
-            environment: entry.sourceName,
-            message: `Variable ${key} is not defined in the contract.`,
-            value: entry.value,
-            debugValues: options.debugValues
-          })
-        );
-        continue;
-      }
-      const validation = validateValueAgainstExpected(variable.expected, entry.value);
-      if (!validation.isValid) {
-        issues.push(
-          createIssue({
-            type: validation.issueType,
-            severity: "error",
-            key,
-            environment: entry.sourceName,
-            message: validation.issueType === "invalid_type" ? `Variable ${key} has invalid type in ${entry.sourceName}.` : `Variable ${key} has invalid value in ${entry.sourceName}.`,
-            value: entry.value,
-            debugValues: options.debugValues,
-            expected: variable.expected,
-            receivedType: validation.receivedType
-          })
-        );
-      }
-      if (isClientSecret(variable, key)) {
-        issues.push(
-          createIssue({
-            type: "secret_exposed",
-            severity: "error",
-            key,
-            environment: entry.sourceName,
-            message: `Secret variable ${key} is marked as client-side.`,
-            value: entry.value,
-            debugValues: options.debugValues,
-            expected: variable.expected
-          })
-        );
-      }
+      diffPresentEntry(key, entry, ctx);
     }
   }
   return buildReport("diff", issues);
@@ -1392,7 +1474,7 @@ function parseEnvSourceContent(content) {
   for (const line of lines) {
     const trimmed = line.trim();
     if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
-    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed);
+    const match = /^(?:export\s+)?([A-Za-z_]\w*)=(.*)$/.exec(trimmed);
     if (match === null) continue;
     const key = match[1] ?? "";
     const rawValue = match[2] ?? "";
@@ -1405,11 +1487,11 @@ async function loadEnvSource(options) {
   try {
     const content = await readFile3(resolvedPath, "utf8");
     return parseEnvSourceContent(content);
-  } catch (errorValue) {
-    if (options.allowMissing === true && errorValue instanceof Error && "code" in errorValue && errorValue.code === "ENOENT") {
+  } catch (error_) {
+    if (options.allowMissing === true && error_ instanceof Error && "code" in error_ && error_.code === "ENOENT") {
       return {};
     }
-    throw errorValue;
+    throw error_;
   }
 }
 
@@ -1423,8 +1505,8 @@ function toJsonString(report, mode) {
 `;
 }
 function formatIssue(issue) {
-  const expected = issue.expected !== void 0 ? ` expected=${issue.expected.type}` : "";
-  const received = issue.receivedType !== void 0 ? ` received=${issue.receivedType}` : "";
+  const expected = issue.expected === void 0 ? "" : ` expected=${issue.expected.type}`;
+  const received = issue.receivedType === void 0 ? "" : ` received=${issue.receivedType}`;
   return `${issue.severity.toUpperCase()} [${issue.code}] ${issue.environment}:${issue.key} ${issue.message}${expected}${received}`;
 }
 function formatHumanReport(report) {
@@ -1433,15 +1515,13 @@ function formatHumanReport(report) {
     `Status: ${report.status.toUpperCase()} (errors=${report.summary.errors}, warnings=${report.summary.warnings}, total=${report.summary.total})`
   );
   if (report.issues.length > 0) {
-    lines.push("");
-    lines.push("Issues:");
+    lines.push("", "Issues:");
     for (const issue of report.issues) {
       lines.push(`- ${formatIssue(issue)}`);
     }
   }
   if (report.recommendations !== void 0 && report.recommendations.length > 0) {
-    lines.push("");
-    lines.push("Recommendations:");
+    lines.push("", "Recommendations:");
     for (const recommendation of report.recommendations) {
       lines.push(`- ${recommendation}`);
     }
@@ -1486,7 +1566,11 @@ var HELP_TEXT = {
     "  --cloud-file <path>       Cloud snapshot JSON file",
     "  --plugin <path>           Plugin module path (repeatable)",
     "  -c, --config <path>       Config file path",
-    "  -h, --help                Show this help"
+    "  -h, --help                Show this help",
+    "",
+    "Exit codes:",
+    "  0  All checks passed (status: ok or warn)",
+    "  1  One or more checks failed (status: fail) or invalid usage"
   ].join("\n"),
   diff: [
     "Usage: env-typegen diff [options]",
@@ -1505,7 +1589,11 @@ var HELP_TEXT = {
     "  --cloud-file <path>       Cloud snapshot JSON file added to diff sources",
     "  --plugin <path>           Plugin module path (repeatable)",
     "  -c, --config <path>       Config file path",
-    "  -h, --help                Show this help"
+    "  -h, --help                Show this help",
+    "",
+    "Exit codes:",
+    "  0  All checks passed (status: ok or warn)",
+    "  1  One or more checks failed (status: fail) or invalid usage"
   ].join("\n"),
   doctor: [
     "Usage: env-typegen doctor [options]",
@@ -1525,7 +1613,11 @@ var HELP_TEXT = {
     "  --cloud-file <path>       Cloud snapshot JSON file",
     "  --plugin <path>           Plugin module path (repeatable)",
     "  -c, --config <path>       Config file path",
-    "  -h, --help                Show this help"
+    "  -h, --help                Show this help",
+    "",
+    "Exit codes:",
+    "  0  All checks passed (status: ok or warn)",
+    "  1  One or more checks failed (status: fail) or invalid usage"
   ].join("\n")
 };
 function resolveConfigRelative(value, configDir) {
@@ -1567,6 +1659,9 @@ async function loadCommandConfig(configPath) {
     return loadConfig(process.cwd());
   }
   const resolvedPath = path11.resolve(configPath);
+  if (!existsSync4(resolvedPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
   const configDir = path11.dirname(resolvedPath);
   const moduleValue = await import(pathToFileURL4(resolvedPath).href);
   if (moduleValue.default === void 0) return void 0;
@@ -1612,7 +1707,10 @@ function parseValidationArgs(argv) {
     }
   });
   const castValues = values;
-  const jsonMode = castValues.json === true ? assignedMode === "off" ? "compact" : assignedMode : "off";
+  let jsonMode = "off";
+  if (castValues.json === true) {
+    jsonMode = assignedMode === "off" ? "compact" : assignedMode;
+  }
   return { values: castValues, jsonMode };
 }
 function resolveStrict(values, fileConfig) {
@@ -1685,12 +1783,12 @@ async function runCheckCommand(args) {
   const provider = context.cloudProvider;
   let environment = args.values.env?.[0] ?? ".env";
   let sourceValues;
-  if (provider !== void 0) {
+  if (provider === void 0) {
+    sourceValues = await loadEnvSource({ filePath: environment, allowMissing: true });
+  } else {
     const cloudFile = context.cloudFile ?? `${provider}.env.json`;
     sourceValues = await loadCloudSource({ provider, filePath: cloudFile });
     environment = `cloud:${provider}`;
-  } else {
-    sourceValues = await loadEnvSource({ filePath: environment, allowMissing: true });
   }
   sourceValues = applySourcePlugins({ environment, values: sourceValues }, context.plugins);
   const report = applyReportPlugins(
@@ -1822,8 +1920,9 @@ async function runValidationCommand(params) {
 }
 
 // src/watch.ts
-import path12 from "path";
 import { watch } from "chokidar";
+import { existsSync as existsSync5 } from "fs";
+import path12 from "path";
 function debounce(fn, delay) {
   let timer;
   return (...args) => {
@@ -1835,6 +1934,13 @@ function debounce(fn, delay) {
   };
 }
 function startWatch({ inputPath, runOptions, cwd = process.cwd() }) {
+  const inputPaths = Array.isArray(inputPath) ? inputPath : [inputPath];
+  for (const singlePath of inputPaths) {
+    if (!existsSync5(singlePath)) {
+      error(`File not found: ${singlePath}`);
+      return process.exit(1);
+    }
+  }
   const inputLabel = Array.isArray(inputPath) ? inputPath.join(", ") : inputPath;
   log(`Watching ${inputLabel} for changes...`);
   void runGenerate(runOptions).catch((err) => {
@@ -1858,6 +1964,9 @@ function startWatch({ inputPath, runOptions, cwd = process.cwd() }) {
         if (reloaded.inferenceRules !== void 0) {
           runOptions.inferenceRules = reloaded.inferenceRules;
         }
+        if (reloaded.output !== void 0) {
+          runOptions.output = reloaded.output;
+        }
       }
       void runGenerate(runOptions).catch((err) => {
         const message = err instanceof Error ? err.message : JSON.stringify(err);
@@ -1875,7 +1984,7 @@ function startWatch({ inputPath, runOptions, cwd = process.cwd() }) {
   const configPaths = CONFIG_FILE_NAMES.map((name) => path12.resolve(cwd, name));
   const configWatcher = watch(configPaths, { persistent: true, ignoreInitial: true });
   for (const event of ["add", "change"]) {
-    configWatcher.on(event, (eventPath) => void handleConfigChange(eventPath));
+    configWatcher.on(event, (eventPath) => handleConfigChange(eventPath));
   }
   process.on("SIGINT", () => {
     void Promise.all([inputWatcher.close(), configWatcher.close()]).then(() => {
@@ -1899,7 +2008,9 @@ var HELP_TEXT2 = [
   "",
   "Options:",
   "  -i, --input <path>         Path to .env.example file(s). May be specified multiple times.",
-  "  -o, --output <path>        Output file path (default: env.generated.ts)",
+  "  -o, --output <path>        Output base path (default: env.generated.ts).",
+  "                             With multiple generators, suffixes are appended:",
+  "                             env.generated.typescript.ts, .zod.ts, .t3.ts, .declaration.d.ts",
   "  -f, --format <name>        Generator format: ts|zod|t3|declaration",
   "                             May be specified multiple times.",
   "  -g, --generator <name>     Backward-compatible alias for --format",
@@ -1910,7 +2021,16 @@ var HELP_TEXT2 = [
   "  -w, --watch                Watch for changes and regenerate",
   "  -c, --config <path>        Path to config file",
   "  -v, --version              Print version",
-  "  -h, --help                 Show this help"
+  "  -h, --help                 Show this help",
+  "",
+  "Config file:",
+  "  Auto-discovered in order: env-typegen.config.mjs \u2192 .js \u2192 .ts (in cwd)",
+  "  CLI flags always override config file values.",
+  "  Use defineConfig() from @xlameiro/env-typegen for IDE autocompletion.",
+  "",
+  "Exit codes:",
+  "  0  Success \u2014 files generated without errors",
+  "  1  Error \u2014 invalid flags or generation failed"
 ].join("\n");
 var VALIDATION_SUBCOMMANDS = /* @__PURE__ */ new Set(["check", "diff", "doctor"]);
 var FORMAT_TO_GENERATOR = {
@@ -1966,6 +2086,15 @@ async function runValidationSubcommand(subcommand, argv) {
     process.exitCode = exitCode;
   }
 }
+async function loadExplicitConfig(configPath, userPath) {
+  if (!existsSync6(configPath)) {
+    throw new Error(`Config file not found: ${userPath}`);
+  }
+  const configDir = path13.dirname(configPath);
+  const mod = await import(pathToFileURL5(configPath).href);
+  const rawConfig = mod.default;
+  return rawConfig ? applyConfigPaths2(rawConfig, configDir) : void 0;
+}
 async function runCli(argv = process.argv.slice(2)) {
   const maybeSubcommand = argv[0];
   if (maybeSubcommand !== void 0 && VALIDATION_SUBCOMMANDS.has(maybeSubcommand)) {
@@ -2001,13 +2130,7 @@ async function runCli(argv = process.argv.slice(2)) {
   if (values.config === void 0) {
     fileConfig = await loadConfig(process.cwd());
   } else {
-    const configPath = path13.resolve(values.config);
-    const configDir = path13.dirname(configPath);
-    const mod = await import(pathToFileURL5(configPath).href);
-    const rawConfig = mod.default;
-    if (rawConfig) {
-      fileConfig = applyConfigPaths2(rawConfig, configDir);
-    }
+    fileConfig = await loadExplicitConfig(path13.resolve(values.config), values.config);
   }
   const cliInput = values.input?.length ? values.input : void 0;
   const input = cliInput ?? fileConfig?.input;