@scuton/dotenv-guard 1.0.0

package/src/cli.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from 'fs';
+import { syncCheck } from './core/sync.js';
+import { validate, inferRules } from './core/validator.js';
+import { checkLeaks, installPreCommitHook } from './core/leak.js';
+import { generateExample, ensureGitignore } from './core/generator.js';
+import { parseEnvFileToMap } from './core/parser.js';
+import { red, green, yellow, gray, bold, dim } from './utils/colors.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function showHelp() {
+  console.log(`
+  ${bold('dotenv-guard')} — Validate env vars, sync .env files, prevent leaks
+
+  ${bold('Usage:')}
+    dotenv-guard <command> [options]
+
+  ${bold('Commands:')}
+    sync             Compare .env with .env.example
+    validate         Validate env var types (from .env.example hints)
+    leak-check       Scan for leaked secrets in git
+    init             Create .env.example + update .gitignore
+    install-hook     Install git pre-commit hook to block .env commits
+
+  ${bold('Options:')}
+    --env <path>     Path to .env file (default: .env)
+    --example <path> Path to .env.example (default: .env.example)
+    -h, --help       Show help
+    -v, --version    Show version
+
+  ${bold('Programmatic:')}
+    import 'dotenv-guard/auto';
+    // Auto-check on import
+    import { guard } from 'dotenv-guard';  // Manual check
+  `);
+}
+
+// Arg parse
+const envPath = args.includes('--env') ? args[args.indexOf('--env') + 1] : '.env';
+const examplePath = args.includes('--example') ? args[args.indexOf('--example') + 1] : '.env.example';
+
+switch (command) {
+  case 'sync': {
+    try {
+      const result = syncCheck(envPath, examplePath);
+      console.log('');
+      console.log(bold('  dotenv-guard sync'));
+      console.log(gray(`  ${result.envPath} ↔ ${result.examplePath}`));
+      console.log('');
+
+      if (result.missing.length > 0) {
+        console.log(red(`  ✖ Missing (${result.missing.length}):`));
+        result.missing.forEach(k => console.log(yellow(`    → ${k}`)));
+        console.log('');
+      }
+
+      if (result.extra.length > 0) {
+        console.log(yellow(`  ⚠ Extra (${result.extra.length}):`));
+        result.extra.forEach(k => console.log(gray(`    → ${k}`)));
+        console.log('');
+      }
+
+      console.log(green(`  ✓ Synced: ${result.synced.length} variables`));
+
+      if (result.missing.length > 0) {
+        console.log('');
+        console.log(dim(`  Add missing variables to ${result.envPath} to fix.`));
+      }
+      console.log('');
+
+      process.exit(result.missing.length > 0 ? 1 : 0);
+    } catch (err: any) {
+      console.error(red(`\n  ✖ ${err.message}\n`));
+      process.exit(1);
+    }
+    break;
+  }
+
+  case 'validate': {
+    try {
+      if (!existsSync(examplePath)) {
+        console.error(red(`\n  ✖ ${examplePath} not found. Run "dotenv-guard init" first.\n`));
+        process.exit(1);
+      }
+
+      const exampleContent = readFileSync(examplePath, 'utf-8');
+      const rules = inferRules(exampleContent);
+
+      // Mevcut env değerlerini al
+      const envMap = existsSync(envPath) ? parseEnvFileToMap(readFileSync(envPath, 'utf-8')) : new Map();
+      const env: Record<string, string | undefined> = {};
+
+      // process.env + .env dosyası birleştir
+      for (const rule of rules) {
+        env[rule.key] = process.env[rule.key] || envMap.get(rule.key);
+      }
+
+      const errors = validate(env, rules);
+
+      console.log('');
+      console.log(bold('  dotenv-guard validate'));
+      console.log('');
+
+      if (errors.length === 0) {
+        console.log(green(`  ✓ All ${rules.length} variables are valid`));
+      } else {
+        console.log(red(`  ✖ ${errors.length} validation error(s):`));
+        console.log('');
+        errors.forEach(e => {
+          console.log(`    ${red('✖')} ${bold(e.key)} ${e.message}`);
+          if (e.value) console.log(gray(`      current value: "${e.value}"`));
+        });
+      }
+      console.log('');
+
+      process.exit(errors.length > 0 ? 1 : 0);
+    } catch (err: any) {
+      console.error(red(`\n  ✖ ${err.message}\n`));
+      process.exit(1);
+    }
+    break;
+  }
+
+  case 'leak-check': {
+    const result = checkLeaks('.');
+    console.log('');
+    console.log(bold('  dotenv-guard leak-check'));
+    console.log('');
+
+    // .gitignore check
+    if (result.gitignoreHasEnv) {
+      console.log(green('  ✓ .gitignore includes .env'));
+    } else {
+      console.log(red('  ✖ .gitignore does NOT include .env'));
+      console.log(gray('    Run: dotenv-guard init'));
+    }
+
+    // Pre-commit hook
+    if (result.preCommitHookInstalled) {
+      console.log(green('  ✓ Pre-commit hook installed'));
+    } else {
+      console.log(yellow('  ⚠ No pre-commit hook'));
+      console.log(gray('    Run: dotenv-guard install-hook'));
+    }
+
+    // Leaks
+    if (result.leaks.length === 0) {
+      console.log(green('  ✓ No .env files tracked in git'));
+    } else {
+      console.log(red(`  ✖ ${result.leaks.length} leaked variable(s) in git:`));
+      console.log('');
+      result.leaks.forEach(l => {
+        const icon = l.severity === 'high' ? red('HIGH') : yellow('MED');
+        console.log(`    [${icon}] ${l.file}:${l.line} — ${bold(l.key)}`);
+      });
+      console.log('');
+      console.log(dim('  Remove tracked files: git rm --cached .env'));
+    }
+    console.log('');
+
+    process.exit(result.leaks.length > 0 ? 1 : 0);
+    break;
+  }
+
+  case 'init': {
+    console.log('');
+    console.log(bold('  dotenv-guard init'));
+    console.log('');
+
+    // .env.example oluştur
+    if (existsSync('.env') && !existsSync('.env.example')) {
+      generateExample('.env', '.env.example');
+      console.log(green('  ✓ Created .env.example from .env'));
+    } else if (existsSync('.env.example')) {
+      console.log(gray('  • .env.example already exists'));
+    } else {
+      console.log(yellow('  ⚠ No .env file found — create one first'));
+    }
+
+    // .gitignore güncelle
+    const updated = ensureGitignore('.');
+    if (updated) {
+      console.log(green('  ✓ Updated .gitignore with .env entries'));
+    } else {
+      console.log(gray('  • .gitignore already includes .env'));
+    }
+
+    console.log('');
+    break;
+  }
+
+  case 'install-hook': {
+    try {
+      installPreCommitHook('.');
+      console.log('');
+      console.log(green(bold('  ✓ Pre-commit hook installed')));
+      console.log(gray('    .env files will be blocked from commits'));
+      console.log(gray('    Bypass with: git commit --no-verify'));
+      console.log('');
+    } catch (err: any) {
+      console.error(red(`\n  ✖ ${err.message}\n`));
+      process.exit(1);
+    }
+    break;
+  }
+
+  case '-v':
+  case '--version':
+    console.log('1.0.0');
+    break;
+
+  case '-h':
+  case '--help':
+  case undefined:
+    showHelp();
+    break;
+
+  default:
+    console.error(red(`\n  Unknown command: ${command}`));
+    showHelp();
+    process.exit(1);
+}

package/src/core/generator.ts

@@ -0,0 +1,49 @@
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
+import { parseEnvFile } from './parser.js';
+
+// .env'den .env.example oluştur (değerleri maskele)
+export function generateExample(envPath: string = '.env', outputPath: string = '.env.example'): string {
+  if (!existsSync(envPath)) throw new Error(`${envPath} not found`);
+
+  const content = readFileSync(envPath, 'utf-8');
+  const entries = parseEnvFile(content);
+
+  const lines: string[] = ['# Environment Variables', '# Copy this file to .env and fill in the values', ''];
+
+  for (const entry of entries) {
+    // Değeri maskele ama tip hint'i bırak
+    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';
+  writeFileSync(outputPath, output, 'utf-8');
+  return output;
+}
+
+// .gitignore'a .env ekle
+export function ensureGitignore(dir: string = '.'): boolean {
+  const gitignorePath = `${dir}/.gitignore`;
+  const envEntries = ['.env', '.env.local', '.env.*.local'];
+
+  let content = '';
+  if (existsSync(gitignorePath)) {
+    content = 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';
+    appendFileSync(gitignorePath, addition, 'utf-8');
+    return true;
+  }
+
+  return false;
+}

package/src/core/leak.ts

@@ -0,0 +1,115 @@
+import { execSync } from 'child_process';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync } from 'fs';
+
+export interface LeakResult {
+  leaks: LeakEntry[];
+  gitignoreHasEnv: boolean;
+  preCommitHookInstalled: boolean;
+}
+
+export interface LeakEntry {
+  file: string;
+  line: number;
+  key: string;
+  severity: 'high' | 'medium' | 'low';
+}
+
+// Hassas key pattern'leri
+const 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,
+];
+
+export function checkLeaks(dir: string = '.'): LeakResult {
+  const leaks: LeakEntry[] = [];
+
+  // .gitignore kontrolü
+  let gitignoreHasEnv = false;
+  const gitignorePath = `${dir}/.gitignore`;
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    gitignoreHasEnv = content.split('\n').some(line =>
+      line.trim() === '.env' || line.trim() === '.env*' || line.trim() === '.env.local'
+    );
+  }
+
+  // Git tracked files'da .env var mı?
+  try {
+    const tracked = 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 = 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 {
+    // git yoksa veya git repo değilse skip
+  }
+
+  // Pre-commit hook var mı?
+  let preCommitHookInstalled = false;
+  const hookPath = `${dir}/.git/hooks/pre-commit`;
+  if (existsSync(hookPath)) {
+    const hookContent = readFileSync(hookPath, 'utf-8');
+    preCommitHookInstalled = hookContent.includes('dotenv-guard');
+  }
+
+  return { leaks, gitignoreHasEnv, preCommitHookInstalled };
+}
+
+// Pre-commit hook oluştur
+export function installPreCommitHook(dir: string = '.'): void {
+  const hookDir = `${dir}/.git/hooks`;
+  const hookPath = `${hookDir}/pre-commit`;
+
+  const hookScript = `#!/bin/sh
+# dotenv-guard pre-commit hook — 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✖ dotenv-guard: Blocked commit — .env file(s) detected:\\033[0m"
+  echo ""
+  for f in $ENV_FILES; do
+    echo "  \\033[33m→ $f\\033[0m"
+  done
+  echo ""
+  echo "  Remove with: git reset HEAD <file>"
+  echo "  Or force commit: git commit --no-verify"
+  echo ""
+  exit 1
+fi
+`;
+
+  mkdirSync(hookDir, { recursive: true });
+  writeFileSync(hookPath, hookScript, 'utf-8');
+  try {
+    chmodSync(hookPath, '755');
+  } catch {
+    // Windows'ta chmod çalışmayabilir
+  }
+}

package/src/core/parser.ts

@@ -0,0 +1,50 @@
+export interface EnvEntry {
+  key: string;
+  value: string;
+  line: number;
+  comment?: string;
+  raw: string;
+}
+
+export function parseEnvFile(content: string): EnvEntry[] {
+  const entries: EnvEntry[] = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+
+    // Boş satır veya comment
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // KEY=VALUE parse
+    const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)/);
+    if (!match) continue;
+
+    const key = match[1];
+    let value = match[2];
+
+    // Tırnak temizle
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    // Inline comment temizle (tırnaksız değerlerde)
+    const commentMatch = value.match(/\s+#\s/);
+    let comment: string | undefined;
+    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;
+}
+
+export function parseEnvFileToMap(content: string): Map<string, string> {
+  const entries = parseEnvFile(content);
+  return new Map(entries.map(e => [e.key, e.value]));
+}

package/src/core/sync.ts

@@ -0,0 +1,34 @@
+import { readFileSync, existsSync } from 'fs';
+import { parseEnvFile } from './parser.js';
+
+export interface SyncResult {
+  missing: string[];      // .env.example'da var ama .env'de yok
+  extra: string[];        // .env'de var ama .env.example'da yok
+  synced: string[];       // İkisinde de var
+  examplePath: string;
+  envPath: string;
+}
+
+export function syncCheck(
+  envPath: string = '.env',
+  examplePath: string = '.env.example'
+): SyncResult {
+  if (!existsSync(examplePath)) {
+    throw new Error(`${examplePath} not found. Run "dotenv-guard init" to create one.`);
+  }
+
+  const exampleContent = readFileSync(examplePath, 'utf-8');
+  const exampleKeys = new Set(parseEnvFile(exampleContent).map(e => e.key));
+
+  let envKeys = new Set<string>();
+  if (existsSync(envPath)) {
+    const envContent = 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 };
+}

package/src/core/validator.ts

@@ -0,0 +1,126 @@
+export type EnvType = 'string' | 'number' | 'boolean' | 'url' | 'email' | 'port' | 'enum';
+
+export interface ValidationRule {
+  key: string;
+  type?: EnvType;
+  required?: boolean;
+  enum?: string[];
+  pattern?: RegExp;
+  min?: number;
+  max?: number;
+}
+
+export interface ValidationError {
+  key: string;
+  message: string;
+  value?: string;
+}
+
+export function validate(
+  env: Record<string, string | undefined>,
+  rules: ValidationRule[]
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  for (const rule of rules) {
+    const value = env[rule.key];
+
+    // Required check
+    if (rule.required !== false && (value === undefined || value === '')) {
+      errors.push({ key: rule.key, message: 'is required but missing or empty' });
+      continue;
+    }
+
+    if (value === undefined || value === '') continue;
+
+    // Type checks
+    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 !== undefined && num < rule.min)
+            errors.push({ key: rule.key, value, message: `must be >= ${rule.min}` });
+          if (rule.max !== undefined && 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;
+    }
+
+    // Custom pattern
+    if (rule.pattern && !rule.pattern.test(value))
+      errors.push({ key: rule.key, value, message: `does not match required pattern` });
+  }
+
+  return errors;
+}
+
+// .env.example'dan otomatik rule çıkar (comment'lerdeki type hint'lerden)
+export function inferRules(exampleContent: string): ValidationRule[] {
+  const lines = exampleContent.split('\n');
+  const rules: ValidationRule[] = [];
+
+  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: ValidationRule = { key, required: true };
+
+    // Comment'ten type hint çıkar
+    const commentMatch = rest.match(/#\s*type:\s*(\w+)/i);
+    if (commentMatch) {
+      rule.type = commentMatch[1].toLowerCase() as EnvType;
+    }
+
+    // Comment'ten required hint
+    if (rest.match(/#.*optional/i)) {
+      rule.required = false;
+    }
+
+    // Comment'ten enum hint: # enum:development,staging,production
+    const enumMatch = rest.match(/#\s*enum:\s*([^\s]+)/i);
+    if (enumMatch) {
+      rule.type = 'enum';
+      rule.enum = enumMatch[1].split(',');
+    }
+
+    // Value'dan type tahmin et
+    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;
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export { parseEnvFile, parseEnvFileToMap } from './core/parser.js';
+export type { EnvEntry } from './core/parser.js';
+import { syncCheck as _syncCheck } from './core/sync.js';
+export { _syncCheck as syncCheck };
+export type { SyncResult } from './core/sync.js';
+export { validate, inferRules } from './core/validator.js';
+export type { ValidationRule, ValidationError, EnvType } from './core/validator.js';
+export { checkLeaks, installPreCommitHook } from './core/leak.js';
+export type { LeakResult, LeakEntry } from './core/leak.js';
+export { generateExample, ensureGitignore } from './core/generator.js';
+
+// Convenience: guard fonksiyonu — tek çağrıda her şeyi kontrol et
+export function guard(options?: {
+  envPath?: string;
+  examplePath?: string;
+  exitOnError?: boolean;
+}): { ok: boolean; errors: string[] } {
+  const envPath = options?.envPath ?? '.env';
+  const examplePath = options?.examplePath ?? '.env.example';
+  const exitOnError = options?.exitOnError ?? true;
+  const errors: string[] = [];
+
+  try {
+    const sync = _syncCheck(envPath, examplePath);
+    if (sync.missing.length > 0) {
+      errors.push(`Missing variables: ${sync.missing.join(', ')}`);
+    }
+  } catch (err: any) {
+    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(`    ✖ ${e}`));
+    console.error('');
+    process.exit(1);
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/utils/colors.ts

@@ -0,0 +1,13 @@
+// chalk kullanmıyoruz — sıfır dependency
+const isColorSupported = process.env.NO_COLOR === undefined && process.stdout.isTTY;
+
+const wrap = (code: number, resetCode: number) => (str: string) =>
+  isColorSupported ? `\x1b[${code}m${str}\x1b[${resetCode}m` : str;
+
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const gray = wrap(90, 39);
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);

package/src/utils/helpers.ts

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+
+export function resolveFilePath(filePath: string, cwd?: string): string {
+  if (filePath.startsWith('/') || filePath.startsWith('\\')) return filePath;
+  return resolve(cwd || process.cwd(), filePath);
+}
+
+export function readFileSafe(filePath: string): string | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export function pluralize(count: number, singular: string, plural?: string): string {
+  return count === 1 ? singular : (plural || singular + 's');
+}