@scuton/dotenv-guard 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,64 @@
+interface EnvEntry {
+    key: string;
+    value: string;
+    line: number;
+    comment?: string;
+    raw: string;
+}
+declare function parseEnvFile(content: string): EnvEntry[];
+declare function parseEnvFileToMap(content: string): Map<string, string>;
+
+interface SyncResult {
+    missing: string[];
+    extra: string[];
+    synced: string[];
+    examplePath: string;
+    envPath: string;
+}
+declare function syncCheck(envPath?: string, examplePath?: string): SyncResult;
+
+type EnvType = 'string' | 'number' | 'boolean' | 'url' | 'email' | 'port' | 'enum';
+interface ValidationRule {
+    key: string;
+    type?: EnvType;
+    required?: boolean;
+    enum?: string[];
+    pattern?: RegExp;
+    min?: number;
+    max?: number;
+}
+interface ValidationError {
+    key: string;
+    message: string;
+    value?: string;
+}
+declare function validate(env: Record<string, string | undefined>, rules: ValidationRule[]): ValidationError[];
+declare function inferRules(exampleContent: string): ValidationRule[];
+
+interface LeakResult {
+    leaks: LeakEntry[];
+    gitignoreHasEnv: boolean;
+    preCommitHookInstalled: boolean;
+}
+interface LeakEntry {
+    file: string;
+    line: number;
+    key: string;
+    severity: 'high' | 'medium' | 'low';
+}
+declare function checkLeaks(dir?: string): LeakResult;
+declare function installPreCommitHook(dir?: string): void;
+
+declare function generateExample(envPath?: string, outputPath?: string): string;
+declare function ensureGitignore(dir?: string): boolean;
+
+declare function guard(options?: {
+    envPath?: string;
+    examplePath?: string;
+    exitOnError?: boolean;
+}): {
+    ok: boolean;
+    errors: string[];
+};
+
+export { type EnvEntry, type EnvType, type LeakEntry, type LeakResult, type SyncResult, type ValidationError, type ValidationRule, checkLeaks, ensureGitignore, generateExample, guard, inferRules, installPreCommitHook, parseEnvFile, parseEnvFileToMap, syncCheck, validate };

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+interface EnvEntry {
+    key: string;
+    value: string;
+    line: number;
+    comment?: string;
+    raw: string;
+}
+declare function parseEnvFile(content: string): EnvEntry[];
+declare function parseEnvFileToMap(content: string): Map<string, string>;
+
+interface SyncResult {
+    missing: string[];
+    extra: string[];
+    synced: string[];
+    examplePath: string;
+    envPath: string;
+}
+declare function syncCheck(envPath?: string, examplePath?: string): SyncResult;
+
+type EnvType = 'string' | 'number' | 'boolean' | 'url' | 'email' | 'port' | 'enum';
+interface ValidationRule {
+    key: string;
+    type?: EnvType;
+    required?: boolean;
+    enum?: string[];
+    pattern?: RegExp;
+    min?: number;
+    max?: number;
+}
+interface ValidationError {
+    key: string;
+    message: string;
+    value?: string;
+}
+declare function validate(env: Record<string, string | undefined>, rules: ValidationRule[]): ValidationError[];
+declare function inferRules(exampleContent: string): ValidationRule[];
+
+interface LeakResult {
+    leaks: LeakEntry[];
+    gitignoreHasEnv: boolean;
+    preCommitHookInstalled: boolean;
+}
+interface LeakEntry {
+    file: string;
+    line: number;
+    key: string;
+    severity: 'high' | 'medium' | 'low';
+}
+declare function checkLeaks(dir?: string): LeakResult;
+declare function installPreCommitHook(dir?: string): void;
+
+declare function generateExample(envPath?: string, outputPath?: string): string;
+declare function ensureGitignore(dir?: string): boolean;
+
+declare function guard(options?: {
+    envPath?: string;
+    examplePath?: string;
+    exitOnError?: boolean;
+}): {
+    ok: boolean;
+    errors: string[];
+};
+
+export { type EnvEntry, type EnvType, type LeakEntry, type LeakResult, type SyncResult, type ValidationError, type ValidationRule, checkLeaks, ensureGitignore, generateExample, guard, inferRules, installPreCommitHook, parseEnvFile, parseEnvFileToMap, syncCheck, validate };

package/dist/index.js

@@ -0,0 +1,331 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  checkLeaks: () => checkLeaks,
+  ensureGitignore: () => ensureGitignore,
+  generateExample: () => generateExample,
+  guard: () => guard,
+  inferRules: () => inferRules,
+  installPreCommitHook: () => installPreCommitHook,
+  parseEnvFile: () => parseEnvFile,
+  parseEnvFileToMap: () => parseEnvFileToMap,
+  syncCheck: () => syncCheck,
+  validate: () => validate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/parser.ts
+function parseEnvFile(content) {
+  const entries = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)/);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2];
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    const commentMatch = value.match(/\s+#\s/);
+    let comment;
+    if (commentMatch && !match[2].startsWith('"') && !match[2].startsWith("'")) {
+      comment = value.slice(commentMatch.index + commentMatch[0].length);
+      value = value.slice(0, commentMatch.index);
+    }
+    entries.push({ key, value, line: i + 1, comment, raw });
+  }
+  return entries;
+}
+function parseEnvFileToMap(content) {
+  const entries = parseEnvFile(content);
+  return new Map(entries.map((e) => [e.key, e.value]));
+}
+
+// src/core/sync.ts
+var import_fs = require("fs");
+function syncCheck(envPath = ".env", examplePath = ".env.example") {
+  if (!(0, import_fs.existsSync)(examplePath)) {
+    throw new Error(`${examplePath} not found. Run "dotenv-guard init" to create one.`);
+  }
+  const exampleContent = (0, import_fs.readFileSync)(examplePath, "utf-8");
+  const exampleKeys = new Set(parseEnvFile(exampleContent).map((e) => e.key));
+  let envKeys = /* @__PURE__ */ new Set();
+  if ((0, import_fs.existsSync)(envPath)) {
+    const envContent = (0, import_fs.readFileSync)(envPath, "utf-8");
+    envKeys = new Set(parseEnvFile(envContent).map((e) => e.key));
+  }
+  const missing = [...exampleKeys].filter((k) => !envKeys.has(k));
+  const extra = [...envKeys].filter((k) => !exampleKeys.has(k));
+  const synced = [...exampleKeys].filter((k) => envKeys.has(k));
+  return { missing, extra, synced, examplePath, envPath };
+}
+
+// src/core/validator.ts
+function validate(env, rules) {
+  const errors = [];
+  for (const rule of rules) {
+    const value = env[rule.key];
+    if (rule.required !== false && (value === void 0 || value === "")) {
+      errors.push({ key: rule.key, message: "is required but missing or empty" });
+      continue;
+    }
+    if (value === void 0 || value === "") continue;
+    switch (rule.type) {
+      case "number": {
+        const num = Number(value);
+        if (isNaN(num)) {
+          errors.push({ key: rule.key, value, message: `must be a number, got "${value}"` });
+        } else {
+          if (rule.min !== void 0 && num < rule.min)
+            errors.push({ key: rule.key, value, message: `must be >= ${rule.min}` });
+          if (rule.max !== void 0 && num > rule.max)
+            errors.push({ key: rule.key, value, message: `must be <= ${rule.max}` });
+        }
+        break;
+      }
+      case "boolean":
+        if (!["true", "false", "1", "0", "yes", "no"].includes(value.toLowerCase()))
+          errors.push({ key: rule.key, value, message: "must be a boolean (true/false/1/0/yes/no)" });
+        break;
+      case "url":
+        try {
+          new URL(value);
+        } catch {
+          errors.push({ key: rule.key, value, message: "must be a valid URL" });
+        }
+        break;
+      case "email":
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
+          errors.push({ key: rule.key, value, message: "must be a valid email" });
+        break;
+      case "port": {
+        const port = Number(value);
+        if (isNaN(port) || port < 1 || port > 65535)
+          errors.push({ key: rule.key, value, message: "must be a valid port (1-65535)" });
+        break;
+      }
+      case "enum":
+        if (rule.enum && !rule.enum.includes(value))
+          errors.push({ key: rule.key, value, message: `must be one of: ${rule.enum.join(", ")}` });
+        break;
+    }
+    if (rule.pattern && !rule.pattern.test(value))
+      errors.push({ key: rule.key, value, message: `does not match required pattern` });
+  }
+  return errors;
+}
+function inferRules(exampleContent) {
+  const lines = exampleContent.split("\n");
+  const rules = [];
+  for (const line of lines) {
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)/);
+    if (!match) continue;
+    const key = match[1];
+    const rest = match[2];
+    const rule = { key, required: true };
+    const commentMatch = rest.match(/#\s*type:\s*(\w+)/i);
+    if (commentMatch) {
+      rule.type = commentMatch[1].toLowerCase();
+    }
+    if (rest.match(/#.*optional/i)) {
+      rule.required = false;
+    }
+    const enumMatch = rest.match(/#\s*enum:\s*([^\s]+)/i);
+    if (enumMatch) {
+      rule.type = "enum";
+      rule.enum = enumMatch[1].split(",");
+    }
+    if (!rule.type) {
+      const value = rest.split("#")[0].trim().replace(/^["']|["']$/g, "");
+      if (value.match(/^https?:\/\//)) rule.type = "url";
+      else if (value.match(/^\d+$/) && key.match(/PORT/i)) rule.type = "port";
+      else if (value.match(/^(true|false)$/i)) rule.type = "boolean";
+      else if (value.match(/^\d+$/)) rule.type = "number";
+    }
+    rules.push(rule);
+  }
+  return rules;
+}
+
+// src/core/leak.ts
+var import_child_process = require("child_process");
+var import_fs2 = require("fs");
+var SENSITIVE_PATTERNS = [
+  /API[_-]?KEY/i,
+  /SECRET/i,
+  /PASSWORD/i,
+  /TOKEN/i,
+  /PRIVATE[_-]?KEY/i,
+  /DATABASE[_-]?URL/i,
+  /MONGO[_-]?URI/i,
+  /REDIS[_-]?URL/i,
+  /AWS[_-]?ACCESS/i,
+  /STRIPE/i,
+  /SENDGRID/i,
+  /TWILIO/i,
+  /ANTHROPIC/i,
+  /OPENAI/i
+];
+function checkLeaks(dir = ".") {
+  const leaks = [];
+  let gitignoreHasEnv = false;
+  const gitignorePath = `${dir}/.gitignore`;
+  if ((0, import_fs2.existsSync)(gitignorePath)) {
+    const content = (0, import_fs2.readFileSync)(gitignorePath, "utf-8");
+    gitignoreHasEnv = content.split("\n").some(
+      (line) => line.trim() === ".env" || line.trim() === ".env*" || line.trim() === ".env.local"
+    );
+  }
+  try {
+    const tracked = (0, import_child_process.execSync)("git ls-files", { cwd: dir, encoding: "utf-8" });
+    const envFiles = tracked.split("\n").filter(
+      (f) => f.match(/^\.env($|\.)/) && !f.endsWith(".example") && !f.endsWith(".template")
+    );
+    for (const file of envFiles) {
+      const content = (0, import_fs2.readFileSync)(`${dir}/${file}`, "utf-8");
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)/);
+        if (match && match[2].trim().length > 0) {
+          const key = match[1];
+          const severity = SENSITIVE_PATTERNS.some((p) => p.test(key)) ? "high" : "medium";
+          leaks.push({ file, line: i + 1, key, severity });
+        }
+      }
+    }
+  } catch {
+  }
+  let preCommitHookInstalled = false;
+  const hookPath = `${dir}/.git/hooks/pre-commit`;
+  if ((0, import_fs2.existsSync)(hookPath)) {
+    const hookContent = (0, import_fs2.readFileSync)(hookPath, "utf-8");
+    preCommitHookInstalled = hookContent.includes("dotenv-guard");
+  }
+  return { leaks, gitignoreHasEnv, preCommitHookInstalled };
+}
+function installPreCommitHook(dir = ".") {
+  const hookDir = `${dir}/.git/hooks`;
+  const hookPath = `${hookDir}/pre-commit`;
+  const hookScript = `#!/bin/sh
+# dotenv-guard pre-commit hook \u2014 prevent .env leaks
+# Installed by: npx dotenv-guard install-hook
+
+ENV_FILES=$(git diff --cached --name-only | grep -E '^\\.env' | grep -v '\\.example$' | grep -v '\\.template$')
+
+if [ -n "$ENV_FILES" ]; then
+  echo ""
+  echo "\\033[31m\u2716 dotenv-guard: Blocked commit \u2014 .env file(s) detected:\\033[0m"
+  echo ""
+  for f in $ENV_FILES; do
+    echo "  \\033[33m\u2192 $f\\033[0m"
+  done
+  echo ""
+  echo "  Remove with: git reset HEAD <file>"
+  echo "  Or force commit: git commit --no-verify"
+  echo ""
+  exit 1
+fi
+`;
+  (0, import_fs2.mkdirSync)(hookDir, { recursive: true });
+  (0, import_fs2.writeFileSync)(hookPath, hookScript, "utf-8");
+  try {
+    (0, import_fs2.chmodSync)(hookPath, "755");
+  } catch {
+  }
+}
+
+// src/core/generator.ts
+var import_fs3 = require("fs");
+function generateExample(envPath = ".env", outputPath = ".env.example") {
+  if (!(0, import_fs3.existsSync)(envPath)) throw new Error(`${envPath} not found`);
+  const content = (0, import_fs3.readFileSync)(envPath, "utf-8");
+  const entries = parseEnvFile(content);
+  const lines = ["# Environment Variables", "# Copy this file to .env and fill in the values", ""];
+  for (const entry of entries) {
+    let placeholder = "";
+    if (entry.value.match(/^https?:\/\//)) placeholder = "https://... # type:url";
+    else if (entry.value.match(/^\d+$/)) placeholder = "0 # type:number";
+    else if (entry.value.match(/^(true|false)$/i)) placeholder = "false # type:boolean";
+    else placeholder = "# type:string";
+    lines.push(`${entry.key}=${placeholder}`);
+  }
+  const output = lines.join("\n") + "\n";
+  (0, import_fs3.writeFileSync)(outputPath, output, "utf-8");
+  return output;
+}
+function ensureGitignore(dir = ".") {
+  const gitignorePath = `${dir}/.gitignore`;
+  const envEntries = [".env", ".env.local", ".env.*.local"];
+  let content = "";
+  if ((0, import_fs3.existsSync)(gitignorePath)) {
+    content = (0, import_fs3.readFileSync)(gitignorePath, "utf-8");
+  }
+  const lines = content.split("\n");
+  const toAdd = envEntries.filter((e) => !lines.some((l) => l.trim() === e));
+  if (toAdd.length > 0) {
+    const addition = "\n# Environment variables\n" + toAdd.join("\n") + "\n";
+    (0, import_fs3.appendFileSync)(gitignorePath, addition, "utf-8");
+    return true;
+  }
+  return false;
+}
+
+// src/index.ts
+function guard(options) {
+  const envPath = options?.envPath ?? ".env";
+  const examplePath = options?.examplePath ?? ".env.example";
+  const exitOnError = options?.exitOnError ?? true;
+  const errors = [];
+  try {
+    const sync = syncCheck(envPath, examplePath);
+    if (sync.missing.length > 0) {
+      errors.push(`Missing variables: ${sync.missing.join(", ")}`);
+    }
+  } catch (err) {
+    if (!err.message.includes("not found")) {
+      errors.push(err.message);
+    }
+  }
+  if (errors.length > 0 && exitOnError) {
+    console.error("\n  dotenv-guard errors:\n");
+    errors.forEach((e) => console.error(`    \u2716 ${e}`));
+    console.error("");
+    process.exit(1);
+  }
+  return { ok: errors.length === 0, errors };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkLeaks,
+  ensureGitignore,
+  generateExample,
+  guard,
+  inferRules,
+  installPreCommitHook,
+  parseEnvFile,
+  parseEnvFileToMap,
+  syncCheck,
+  validate
+});

package/dist/index.mjs

@@ -0,0 +1,50 @@
+import {
+  checkLeaks,
+  ensureGitignore,
+  generateExample,
+  inferRules,
+  installPreCommitHook,
+  validate
+} from "./chunk-QXZQR35R.mjs";
+import {
+  parseEnvFile,
+  parseEnvFileToMap,
+  syncCheck
+} from "./chunk-YYFNUR7Y.mjs";
+
+// src/index.ts
+function guard(options) {
+  const envPath = options?.envPath ?? ".env";
+  const examplePath = options?.examplePath ?? ".env.example";
+  const exitOnError = options?.exitOnError ?? true;
+  const errors = [];
+  try {
+    const sync = syncCheck(envPath, examplePath);
+    if (sync.missing.length > 0) {
+      errors.push(`Missing variables: ${sync.missing.join(", ")}`);
+    }
+  } catch (err) {
+    if (!err.message.includes("not found")) {
+      errors.push(err.message);
+    }
+  }
+  if (errors.length > 0 && exitOnError) {
+    console.error("\n  dotenv-guard errors:\n");
+    errors.forEach((e) => console.error(`    \u2716 ${e}`));
+    console.error("");
+    process.exit(1);
+  }
+  return { ok: errors.length === 0, errors };
+}
+export {
+  checkLeaks,
+  ensureGitignore,
+  generateExample,
+  guard,
+  inferRules,
+  installPreCommitHook,
+  parseEnvFile,
+  parseEnvFileToMap,
+  syncCheck,
+  validate
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@scuton/dotenv-guard",
+  "version": "1.0.0",
+  "description": "Validate env vars, sync .env with .env.example, prevent secret leaks. Zero dependencies.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dotenv-guard": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./auto": {
+      "import": "./dist/auto.mjs",
+      "require": "./dist/auto.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts src/auto.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts src/auto.ts --format cjs,esm --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "dotenv", "env", "environment", "variables", "validation",
+    "guard", "security", "secrets", "leak-prevention", "config",
+    "typescript", "cli", "zero-dependency"
+  ],
+  "author": "Scuton Technology <info@scuton.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scuton-technology/dotenv-guard.git"
+  },
+  "homepage": "https://github.com/scuton-technology/dotenv-guard",
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsup": "^8.0.0",
+    "vitest": "^2.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/auto.ts

@@ -0,0 +1,28 @@
+// Bu dosya import edildiğinde otomatik olarak .env kontrolü yapar
+// Kullanım: import 'dotenv-guard/auto';
+
+import { syncCheck } from './core/sync.js';
+import { red, yellow, bold } from './utils/colors.js';
+
+try {
+  const result = syncCheck();
+
+  if (result.missing.length > 0) {
+    console.error('');
+    console.error(red(bold('  ✖ dotenv-guard: Missing environment variables')));
+    console.error('');
+    for (const key of result.missing) {
+      console.error(yellow(`    → ${key}`));
+    }
+    console.error('');
+    console.error(`  These variables are in ${result.examplePath} but missing from ${result.envPath}`);
+    console.error(`  Run: ${bold('dotenv-guard sync')} to see details`);
+    console.error('');
+    process.exit(1);
+  }
+} catch (err: any) {
+  // .env.example yoksa sessizce geç (her projede olmayabilir)
+  if (!err.message.includes('not found')) {
+    console.warn(yellow(`  ⚠ dotenv-guard: ${err.message}`));
+  }
+}