node-safe-env 0.1.0

package/dist/cli.js

@@ -0,0 +1,1019 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { pathToFileURL as pathToFileURL2 } from "url";
+
+// src/cli/utils/parseArgs.ts
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    const flagName = token.slice(2);
+    const next = rest[index + 1];
+    if (!next || next.startsWith("--")) {
+      flags[flagName] = true;
+      continue;
+    }
+    flags[flagName] = next;
+    index += 1;
+  }
+  return {
+    command,
+    flags,
+    positionals
+  };
+}
+
+// src/errors/EnvValidationError.ts
+var EnvValidationError = class extends Error {
+  constructor(issues) {
+    super(
+      [
+        "Environment validation failed:",
+        ...issues.map((issue) => `- [${issue.code}] ${issue.message}`)
+      ].join("\n")
+    );
+    this.name = "EnvValidationError";
+    this.issues = issues;
+  }
+};
+
+// src/createEnv.ts
+import path2 from "path";
+
+// src/flattenSchema.ts
+function isEnvRule(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+function toEnvKey(path4) {
+  return path4.map((segment) => segment.toUpperCase()).join("_");
+}
+function flattenSchema(schema, parentPath = []) {
+  const entries = [];
+  for (const [key, value] of Object.entries(schema)) {
+    const currentPath = [...parentPath, key];
+    if (isEnvRule(value)) {
+      entries.push({
+        path: currentPath,
+        envKey: toEnvKey(currentPath),
+        rule: value
+      });
+      continue;
+    }
+    if (typeof value === "object" && value !== null) {
+      entries.push(
+        ...flattenSchema(value, currentPath)
+      );
+    }
+  }
+  return entries;
+}
+
+// src/findUnknownEnvKeys.ts
+function findUnknownEnvKeys(schema, source) {
+  const knownKeys = new Set(flattenSchema(schema).map((entry) => entry.envKey));
+  const issues = [];
+  for (const key of Object.keys(source)) {
+    if (source[key] === void 0) {
+      continue;
+    }
+    if (knownKeys.has(key)) {
+      continue;
+    }
+    issues.push({
+      key,
+      code: "unknown_key",
+      message: `Environment variable "${key}" is not defined in the schema.`
+    });
+  }
+  return issues;
+}
+
+// src/loadEnvFiles.ts
+import fs from "fs";
+import path from "path";
+var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function stripInlineComment(input) {
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let isEscaped = false;
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (isEscaped) {
+      isEscaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      isEscaped = true;
+      continue;
+    }
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      continue;
+    }
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      continue;
+    }
+    if (char === "#" && !inSingleQuote && !inDoubleQuote && (index === 0 || /\s/.test(input[index - 1] ?? ""))) {
+      return input.slice(0, index).trimEnd();
+    }
+  }
+  return input.trimEnd();
+}
+function parseEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return /* @__PURE__ */ Object.create(null);
+  }
+  const content = fs.readFileSync(filePath, "utf8");
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const rawLine of content.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    if (line.startsWith("export ")) {
+      line = line.slice("export ".length).trim();
+      if (!line) {
+        continue;
+      }
+    }
+    const equalIndex = line.indexOf("=");
+    if (equalIndex <= 0) {
+      continue;
+    }
+    const key = line.slice(0, equalIndex).trim();
+    if (!ENV_KEY_PATTERN.test(key)) {
+      continue;
+    }
+    let value = stripInlineComment(line.slice(equalIndex + 1)).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function loadEnvFiles(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV ?? "development";
+  const base = parseEnvFile(path.join(cwd, ".env"));
+  const local = parseEnvFile(path.join(cwd, ".env.local"));
+  const environment = parseEnvFile(path.join(cwd, `.env.${nodeEnv}`));
+  const custom = options.envFile ? parseEnvFile(path.resolve(cwd, options.envFile)) : /* @__PURE__ */ Object.create(null);
+  return {
+    base,
+    local,
+    environment,
+    custom
+  };
+}
+
+// src/mergeSources.ts
+function mergeSources(files, runtimeValues = process.env) {
+  return Object.assign(
+    /* @__PURE__ */ Object.create(null),
+    files.base,
+    files.local,
+    files.environment,
+    files.custom,
+    runtimeValues
+  );
+}
+
+// src/applyTransform.ts
+function applyTransform(key, rule, result) {
+  if (result.issue || result.value === void 0 || !rule.transform) {
+    return result;
+  }
+  try {
+    return {
+      value: rule.transform(result.value)
+    };
+  } catch (error) {
+    const message = error instanceof Error && error.message ? error.message : `Environment variable "${key}" failed transform.`;
+    return {
+      issue: {
+        key,
+        code: "invalid_custom",
+        message
+      }
+    };
+  }
+}
+
+// src/validators/boolean.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
+var FALSE_VALUES = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
+var validateBoolean = ({ key, rawValue }) => {
+  const normalized = rawValue.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) {
+    return { value: true };
+  }
+  if (FALSE_VALUES.has(normalized)) {
+    return { value: false };
+  }
+  return {
+    issue: {
+      key,
+      code: "invalid_boolean",
+      message: `Environment variable "${key}" must be a valid boolean.`
+    }
+  };
+};
+
+// src/validators/enum.ts
+var validateEnum = ({ key, rawValue, rule }) => {
+  const enumRule = rule;
+  if (!enumRule.values.includes(rawValue)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_enum",
+        message: `Environment variable "${key}" must be one of: ${enumRule.values.join(", ")}.`
+      }
+    };
+  }
+  return { value: rawValue };
+};
+
+// src/validators/json.ts
+var validateJson = ({ key, rawValue }) => {
+  try {
+    const parsed = JSON.parse(rawValue);
+    return { value: parsed };
+  } catch {
+    return {
+      issue: {
+        key,
+        code: "invalid_json",
+        message: `Environment variable "${key}" must contain valid JSON.`
+      }
+    };
+  }
+};
+
+// src/validators/number.ts
+var validateNumber = ({ key, rawValue }) => {
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_number",
+        message: `Environment variable "${key}" must be a valid number.`
+      }
+    };
+  }
+  return { value: parsed };
+};
+
+// src/validators/port.ts
+var validatePort = ({ key, rawValue }) => {
+  const num = Number(rawValue);
+  if (!Number.isInteger(num) || num < 1 || num > 65535) {
+    return {
+      issue: {
+        key,
+        code: "invalid_port",
+        message: `Environment variable "${key}" must be a valid port (1\u201365535).`
+      }
+    };
+  }
+  return { value: num };
+};
+
+// src/validators/string.ts
+var validateString = ({ rawValue }) => {
+  return { value: rawValue };
+};
+
+// src/validators/url.ts
+var validateUrl = ({ key, rawValue }) => {
+  try {
+    new URL(rawValue);
+    return { value: rawValue };
+  } catch {
+    return {
+      issue: {
+        key,
+        code: "invalid_url",
+        message: `Environment variable "${key}" must be a valid URL.`
+      }
+    };
+  }
+};
+
+// src/validators/int.ts
+var validateInt = ({ key, rawValue }) => {
+  const parsed = Number(rawValue);
+  if (!Number.isInteger(parsed)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_number",
+        message: `Environment variable "${key}" must be a valid integer.`
+      }
+    };
+  }
+  return { value: parsed };
+};
+
+// src/validators/float.ts
+var validateFloat = ({ key, rawValue }) => {
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_number",
+        message: `Environment variable "${key}" must be a valid float.`
+      }
+    };
+  }
+  return { value: parsed };
+};
+
+// src/validators/array.ts
+var validateArray = ({ key, rawValue, rule }) => {
+  const arrayRule = rule;
+  const separator = arrayRule.separator ?? ",";
+  const trimItems = arrayRule.trimItems ?? true;
+  const allowEmptyItems = arrayRule.allowEmptyItems ?? false;
+  const splitValues = rawValue.split(separator);
+  const parsed = trimItems ? splitValues.map((item) => item.trim()) : splitValues;
+  if (!allowEmptyItems && parsed.some((item) => item === "")) {
+    const issue = {
+      key,
+      code: "invalid_array",
+      message: `Environment variable "${key}" cannot contain empty array items`
+    };
+    return { issue };
+  }
+  return { value: parsed };
+};
+
+// src/validators/custom.ts
+var validateCustom = ({ key, rawValue, rule }) => {
+  const customRule = rule;
+  try {
+    const parsed = customRule.parse(rawValue);
+    return { value: parsed };
+  } catch (error) {
+    const message = error instanceof Error && error.message ? error.message : `Environment variable "${key}" failed custom validation.`;
+    return {
+      issue: {
+        key,
+        code: "invalid_custom",
+        message
+      }
+    };
+  }
+};
+
+// src/validators/email.ts
+var validateEmail = ({ key, rawValue, rule }) => {
+  const emailRule = rule;
+  void emailRule;
+  const value = rawValue.trim();
+  if (!value) {
+    const issue = {
+      key,
+      code: "invalid_email",
+      message: `Environment variable "${key}" must be a valid email address`
+    };
+    return { issue };
+  }
+  if (/\s/.test(value)) {
+    const issue = {
+      key,
+      code: "invalid_email",
+      message: `Environment variable "${key}" must be a valid email address`
+    };
+    return { issue };
+  }
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(value)) {
+    const issue = {
+      key,
+      code: "invalid_email",
+      message: `Environment variable "${key}" must be a valid email address`
+    };
+    return { issue };
+  }
+  return {
+    value
+  };
+};
+
+// src/validators/date.ts
+function isValidDate(date) {
+  return !Number.isNaN(date.getTime());
+}
+var validateDate = ({ key, rawValue, rule }) => {
+  const dateRule = rule;
+  void dateRule;
+  const value = rawValue.trim();
+  if (!value) {
+    const issue = {
+      key,
+      code: "invalid_date",
+      message: `Environment variable "${key}" must be a valid ISO date`
+    };
+    return { issue };
+  }
+  const isoDateRegex = /^\d{4}-\d{2}-\d{2}$/;
+  const isoDateTimeRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/;
+  if (!isoDateRegex.test(value) && !isoDateTimeRegex.test(value)) {
+    const issue = {
+      key,
+      code: "invalid_date",
+      message: `Environment variable "${key}" must be a valid ISO date string`
+    };
+    return { issue };
+  }
+  const parsed = new Date(value);
+  if (!isValidDate(parsed)) {
+    const issue = {
+      key,
+      code: "invalid_date",
+      message: `Environment variable "${key}" must be a valid date`
+    };
+    return { issue };
+  }
+  if (isoDateRegex.test(value)) {
+    const [year, month, day] = value.split("-").map(Number);
+    if (parsed.getUTCFullYear() !== year || parsed.getUTCMonth() + 1 !== month || parsed.getUTCDate() !== day) {
+      const issue = {
+        key,
+        code: "invalid_date",
+        message: `Environment variable "${key}" must be a real calendar date`
+      };
+      return { issue };
+    }
+  }
+  return {
+    value: parsed
+  };
+};
+
+// src/validators/index.ts
+var validators = {
+  string: validateString,
+  number: validateNumber,
+  boolean: validateBoolean,
+  enum: validateEnum,
+  url: validateUrl,
+  port: validatePort,
+  json: validateJson,
+  int: validateInt,
+  float: validateFloat,
+  array: validateArray,
+  custom: validateCustom,
+  email: validateEmail,
+  date: validateDate
+};
+
+// src/parseValue.ts
+function parseValue(key, rawValue, rule) {
+  const validator = validators[rule.type];
+  const result = validator({
+    key,
+    rawValue,
+    rule
+  });
+  return applyTransform(key, rule, result);
+}
+
+// src/setNestedValue.ts
+function setNestedValue(target, path4, value) {
+  let current = target;
+  for (let index = 0; index < path4.length - 1; index += 1) {
+    const segment = path4[index];
+    const existing = current[segment];
+    if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
+      current[segment] = {};
+    }
+    current = current[segment];
+  }
+  current[path4[path4.length - 1]] = value;
+}
+
+// src/createEnv.ts
+function isEmptyString(value) {
+  return value.trim() === "";
+}
+function defaultToRawValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return JSON.stringify(value);
+}
+function resolveDefaultValue(value) {
+  return typeof value === "function" ? value() : value;
+}
+function parseDefaultValue(envKey, rule) {
+  const defaultKind = typeof rule.default === "function" ? "function" : "static";
+  let resolvedDefault;
+  try {
+    resolvedDefault = resolveDefaultValue(rule.default);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      issue: {
+        key: envKey,
+        code: "invalid_default",
+        message: `Default function for "${envKey}" threw an error: ${message}`
+      },
+      defaultKind
+    };
+  }
+  const rawDefault = defaultToRawValue(resolvedDefault);
+  return {
+    ...parseValue(envKey, rawDefault, rule),
+    defaultKind,
+    rawDefault
+  };
+}
+function countKeys(source) {
+  return Object.values(source).filter((value) => typeof value === "string").length;
+}
+function buildLoadedFileReport(loadedFiles, cwd, nodeEnv, envFile) {
+  return [
+    {
+      source: ".env",
+      path: path2.join(cwd, ".env"),
+      keyCount: countKeys(loadedFiles.base)
+    },
+    {
+      source: ".env.local",
+      path: path2.join(cwd, ".env.local"),
+      keyCount: countKeys(loadedFiles.local)
+    },
+    {
+      source: ".env.environment",
+      path: path2.join(cwd, `.env.${nodeEnv}`),
+      keyCount: countKeys(loadedFiles.environment)
+    },
+    {
+      source: "custom",
+      path: envFile ? path2.resolve(cwd, envFile) : void 0,
+      keyCount: countKeys(loadedFiles.custom)
+    }
+  ];
+}
+function buildSourceTrace(loadedFiles, runtimeValues) {
+  const trace = /* @__PURE__ */ Object.create(null);
+  const applySource = (source, label) => {
+    for (const [key, raw] of Object.entries(source)) {
+      if (typeof raw === "string") {
+        trace[key] = { source: label, raw };
+      }
+    }
+  };
+  applySource(loadedFiles.base, ".env");
+  applySource(loadedFiles.local, ".env.local");
+  applySource(loadedFiles.environment, ".env.environment");
+  applySource(loadedFiles.custom, "custom");
+  applySource(runtimeValues, "process.env");
+  return trace;
+}
+function maskDebugValue(value, sensitive) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return sensitive ? "***" : value;
+}
+function resolveDebugLogger(debug) {
+  if (debug === true) {
+    return (report) => {
+      console.info(report);
+    };
+  }
+  if (debug && typeof debug === "object" && debug.logger) {
+    return debug.logger;
+  }
+  return void 0;
+}
+function createEnv(schema, options = {}) {
+  const debugEnabled = options.debug !== void 0 && options.debug !== false;
+  const debugLogger = debugEnabled ? resolveDebugLogger(options.debug) : void 0;
+  const debugKeys = [];
+  let source;
+  let loadedFileReport = [];
+  let sourceTrace = /* @__PURE__ */ Object.create(null);
+  if (options.source) {
+    source = options.source;
+    if (debugEnabled) {
+      for (const [key, raw] of Object.entries(source)) {
+        if (typeof raw === "string") {
+          sourceTrace[key] = { source: "process.env", raw };
+        }
+      }
+    }
+  } else {
+    const loadedFiles = loadEnvFiles({
+      cwd: options.cwd,
+      nodeEnv: options.nodeEnv,
+      envFile: options.envFile
+    });
+    source = mergeSources(loadedFiles, process.env);
+    if (debugEnabled) {
+      const cwd = options.cwd ?? process.cwd();
+      const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV ?? "development";
+      loadedFileReport = buildLoadedFileReport(
+        loadedFiles,
+        cwd,
+        nodeEnv,
+        options.envFile
+      );
+      sourceTrace = buildSourceTrace(loadedFiles, process.env);
+    }
+  }
+  const issues = [];
+  const result = {};
+  const flattenedSchema = flattenSchema(schema);
+  if (options.strict) {
+    issues.push(
+      ...findUnknownEnvKeys(schema, source)
+    );
+  }
+  for (const entry of flattenedSchema) {
+    const { path: path4, envKey, rule } = entry;
+    const currentValue = source[envKey];
+    const sourceInfo = sourceTrace[envKey];
+    const sensitive = rule.sensitive === true;
+    const defaultKind = rule.default === void 0 ? void 0 : typeof rule.default === "function" ? "function" : "static";
+    const pushDebugEntry = (status, values) => {
+      if (!debugEnabled) {
+        return;
+      }
+      debugKeys.push({
+        key: envKey,
+        ruleType: rule.type,
+        source: values.source,
+        usedDefault: values.usedDefault,
+        defaultKind: values.defaultKind,
+        raw: maskDebugValue(values.raw, sensitive),
+        parsed: maskDebugValue(values.parsed, sensitive),
+        status,
+        issue: values.issue
+      });
+    };
+    if (typeof currentValue !== "string") {
+      if (rule.default !== void 0) {
+        const parsedDefault = parseDefaultValue(envKey, rule);
+        if (parsedDefault.issue) {
+          issues.push(parsedDefault.issue);
+          pushDebugEntry("issue", {
+            source: "default",
+            usedDefault: true,
+            defaultKind: parsedDefault.defaultKind,
+            raw: parsedDefault.rawDefault,
+            issue: parsedDefault.issue
+          });
+          continue;
+        }
+        pushDebugEntry("defaulted", {
+          source: "default",
+          usedDefault: true,
+          defaultKind: parsedDefault.defaultKind,
+          raw: parsedDefault.rawDefault,
+          parsed: parsedDefault.value
+        });
+        setNestedValue(result, path4, parsedDefault.value);
+        continue;
+      }
+      if (rule.required) {
+        const issue = {
+          key: envKey,
+          code: "missing",
+          message: `Missing required environment variable "${envKey}".`
+        };
+        issues.push(issue);
+        pushDebugEntry("missing", {
+          source: "missing",
+          usedDefault: false,
+          defaultKind,
+          issue
+        });
+      } else {
+        pushDebugEntry("missing", {
+          source: "missing",
+          usedDefault: false,
+          defaultKind
+        });
+      }
+      continue;
+    }
+    const rawValue = currentValue;
+    if (!rule.allowEmpty && isEmptyString(rawValue)) {
+      if (rule.default !== void 0) {
+        const parsedDefault = parseDefaultValue(envKey, rule);
+        if (parsedDefault.issue) {
+          issues.push(parsedDefault.issue);
+          pushDebugEntry("issue", {
+            source: "default",
+            usedDefault: true,
+            defaultKind: parsedDefault.defaultKind,
+            raw: parsedDefault.rawDefault,
+            issue: parsedDefault.issue
+          });
+          continue;
+        }
+        pushDebugEntry("defaulted", {
+          source: "default",
+          usedDefault: true,
+          defaultKind: parsedDefault.defaultKind,
+          raw: parsedDefault.rawDefault,
+          parsed: parsedDefault.value
+        });
+        setNestedValue(result, path4, parsedDefault.value);
+        continue;
+      }
+      const issue = {
+        key: envKey,
+        code: "empty",
+        message: `Environment variable "${envKey}" cannot be empty.`
+      };
+      issues.push(issue);
+      pushDebugEntry("empty", {
+        source: sourceInfo?.source ?? "process.env",
+        usedDefault: false,
+        defaultKind,
+        raw: rawValue,
+        issue
+      });
+      continue;
+    }
+    const parsed = parseValue(envKey, rawValue, rule);
+    if (parsed.issue) {
+      issues.push(parsed.issue);
+      pushDebugEntry("issue", {
+        source: sourceInfo?.source ?? "process.env",
+        usedDefault: false,
+        defaultKind,
+        raw: rawValue,
+        issue: parsed.issue
+      });
+      continue;
+    }
+    pushDebugEntry("parsed", {
+      source: sourceInfo?.source ?? "process.env",
+      usedDefault: false,
+      defaultKind,
+      raw: rawValue,
+      parsed: parsed.value
+    });
+    setNestedValue(result, path4, parsed.value);
+  }
+  if (debugLogger) {
+    debugLogger({
+      loadedFiles: loadedFileReport,
+      keys: debugKeys
+    });
+  }
+  if (issues.length > 0) {
+    throw new EnvValidationError(issues);
+  }
+  return result;
+}
+
+// src/cli/utils/formatIssues.ts
+function formatIssues(issues) {
+  return issues.map((issue) => `- ${issue.key}: ${issue.message}`).join("\n");
+}
+
+// src/cli/utils/loadSchemaModule.ts
+import path3 from "path";
+import { pathToFileURL } from "url";
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+async function loadSchemaModule(schemaPath) {
+  const absolutePath = path3.resolve(schemaPath);
+  const moduleUrl = pathToFileURL(absolutePath).href;
+  const mod = await import(moduleUrl);
+  const schemaCandidate = mod.default ?? mod.schema;
+  if (!isObject(schemaCandidate)) {
+    throw new Error(
+      `Schema module "${schemaPath}" must export a schema as default export or named export "schema".`
+    );
+  }
+  return schemaCandidate;
+}
+
+// src/cli/commands/validate.ts
+async function runValidateCommand(options) {
+  try {
+    const schema = await loadSchemaModule(options.schemaPath);
+    createEnv(schema, {
+      cwd: options.cwd,
+      envFile: options.envFile,
+      nodeEnv: options.nodeEnv,
+      strict: options.strict
+    });
+    console.log("\u2713 Environment validation passed.");
+    return 0;
+  } catch (error) {
+    if (error instanceof EnvValidationError) {
+      console.error("Environment validation failed:\n");
+      console.error(formatIssues(error.issues));
+      return 1;
+    }
+    const message = error instanceof Error ? error.message : "Unknown CLI error";
+    console.error(`CLI error: ${message}`);
+    return 1;
+  }
+}
+
+// src/readEnvFileSource.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+function stripQuotes(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function readEnvFileSource(filePath) {
+  if (!existsSync(filePath)) {
+    return {};
+  }
+  const content = readFileSync(filePath, "utf8");
+  const source = {};
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, equalsIndex).trim();
+    const rawValue = trimmed.slice(equalsIndex + 1).trim();
+    if (!key) {
+      continue;
+    }
+    source[key] = stripQuotes(rawValue);
+  }
+  return source;
+}
+function resolveExampleEnvPath(cwd = process.cwd(), exampleFile = ".env.example") {
+  return resolve(cwd, exampleFile);
+}
+
+// src/validateExampleEnv.ts
+function validateExampleEnv(schema, exampleSource) {
+  const issues = [];
+  const flattenedSchema = flattenSchema(schema);
+  const expectedKeys = new Set(flattenedSchema.map((entry) => entry.envKey));
+  for (const entry of flattenedSchema) {
+    const { envKey } = entry;
+    if (!(envKey in exampleSource)) {
+      issues.push({
+        key: envKey,
+        code: "missing_example_key",
+        message: `Environment variable "${envKey}" is missing from .env.example.`
+      });
+    }
+  }
+  for (const key of Object.keys(exampleSource)) {
+    if (exampleSource[key] === void 0) {
+      continue;
+    }
+    if (expectedKeys.has(key)) {
+      continue;
+    }
+    issues.push({
+      key,
+      code: "unknown_example_key",
+      message: `Environment variable "${key}" in .env.example is not defined in the schema.`
+    });
+  }
+  return issues;
+}
+
+// src/validateExampleEnvFile.ts
+function validateExampleEnvFile(schema, options = {}) {
+  const filePath = resolveExampleEnvPath(options.cwd, options.exampleFile);
+  const exampleSource = readEnvFileSource(filePath);
+  return validateExampleEnv(schema, exampleSource);
+}
+
+// src/cli/commands/validateExample.ts
+async function runValidateExampleCommand(options) {
+  try {
+    const schema = await loadSchemaModule(options.schemaPath);
+    const issues = validateExampleEnvFile(schema, {
+      cwd: options.cwd,
+      exampleFile: options.exampleFile
+    });
+    if (issues.length > 0) {
+      console.error(".env.example validation failed:\n");
+      console.error(formatIssues(issues));
+      return 1;
+    }
+    console.log("\u2713 .env.example validation passed.");
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown CLI error";
+    console.error(`CLI error: ${message}`);
+    return 1;
+  }
+}
+
+// src/cli/index.ts
+function printHelp(io) {
+  io.log(`node-safe-env CLI
+
+Usage:
+  node-safe-env validate --schema <path> [--cwd <path>] [--env-file <path>] [--node-env <value>] [--strict]
+  node-safe-env validate-example --schema <path> [--cwd <path>] [--example-file <path>]
+
+Commands:
+  validate           Validate environment variables using a schema
+  validate-example   Validate a .env.example file against a schema
+
+Options:
+  --schema <path>        Path to schema module
+  --cwd <path>           Working directory for env file loading
+  --env-file <path>      Custom env file path for validate
+  --node-env <value>     NODE_ENV override for validate
+  --strict               Enable strict mode for unknown keys
+  --example-file <path>  Custom example file path for validate-example
+  --help                 Show this help
+`);
+}
+function getStringFlag(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+async function runCli(argv, io = {
+  log: console.log,
+  error: console.error
+}) {
+  const parsed = parseArgs(argv);
+  if (!parsed.command || parsed.flags.help || parsed.command === "help") {
+    printHelp(io);
+    return 0;
+  }
+  const schemaPath = getStringFlag(parsed.flags, "schema");
+  if (!schemaPath) {
+    io.error('Missing required flag "--schema".\n');
+    printHelp(io);
+    return 1;
+  }
+  if (parsed.command === "validate") {
+    return runValidateCommand({
+      schemaPath,
+      cwd: getStringFlag(parsed.flags, "cwd"),
+      envFile: getStringFlag(parsed.flags, "env-file"),
+      nodeEnv: getStringFlag(parsed.flags, "node-env"),
+      strict: parsed.flags.strict === true
+    });
+  }
+  if (parsed.command === "validate-example") {
+    return runValidateExampleCommand({
+      schemaPath,
+      cwd: getStringFlag(parsed.flags, "cwd"),
+      exampleFile: getStringFlag(parsed.flags, "example-file")
+    });
+  }
+  io.error(`Unknown command "${parsed.command}".
+`);
+  printHelp(io);
+  return 1;
+}
+async function main() {
+  const exitCode = await runCli(process.argv.slice(2));
+  process.exitCode = exitCode;
+}
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+  return import.meta.url === pathToFileURL2(entry).href;
+}
+if (isDirectRun()) {
+  void main();
+}
+export {
+  runCli
+};
+//# sourceMappingURL=cli.js.map