@scuton/dotenv-guard 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug Report
+about: Report a bug in dotenv-guard
+title: "[Bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce:
+1. ...
+2. ...
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- Node.js version:
+- dotenv-guard version:
+- OS:

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature Request
+about: Suggest a feature for dotenv-guard
+title: "[Feature] "
+labels: enhancement
+---
+
+**Problem**
+What problem does this solve?
+
+**Proposed solution**
+How should it work?
+
+**Alternatives considered**
+Any other approaches you've thought about.

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [16, 18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test -- --run

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to dotenv-guard
+
+Thanks for your interest in contributing!
+
+## Setup
+
+```bash
+git clone https://github.com/scuton-technology/dotenv-guard.git
+cd dotenv-guard
+npm install
+npm run build
+npm test
+```
+
+## Development
+
+```bash
+npm run dev    # Watch mode
+npm test       # Run tests
+npm run build  # Production build
+```
+
+## Guidelines
+
+- Zero runtime dependencies — use Node.js built-ins only
+- Write tests for new features
+- Follow existing code style
+- Keep it simple and fast
+
+## Pull Requests
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit changes (`git commit -m 'feat: add my feature'`)
+4. Push (`git push origin feature/my-feature`)
+5. Open a PR
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/scuton-technology/dotenv-guard/issues) with the provided templates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scuton Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+<div align="center">
+
+# dotenv-guard
+
+**Validate env vars. Sync .env files. Prevent secret leaks.**
+
+**Zero dependencies.** Works with any Node.js project.
+
+[![npm](https://img.shields.io/npm/v/dotenv-guard)](https://www.npmjs.com/package/dotenv-guard)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install dotenv-guard
+```
+
+## Quick Start
+
+Add one line to your app entry:
+
+```typescript
+import 'dotenv-guard/auto'; // App won't start if .env is missing required variables
+```
+
+Or use the CLI:
+
+```bash
+npx dotenv-guard sync          # .env vs .env.example
+npx dotenv-guard validate      # Check types
+npx dotenv-guard leak-check    # Find leaked secrets
+npx dotenv-guard init          # Create .env.example + .gitignore
+npx dotenv-guard install-hook  # Pre-commit hook
+```
+
+## Type Hints
+
+Add type hints in .env.example comments:
+
+```bash
+DATABASE_URL=postgresql://... # type:url
+PORT=3000 # type:port
+DEBUG=false # type:boolean
+NODE_ENV=development # enum:development,staging,production
+REDIS_URL= # type:url optional
+```
+
+## Programmatic API
+
+```typescript
+import { guard, syncCheck, validate, checkLeaks } from 'dotenv-guard';
+
+// Quick guard — exits if missing vars
+guard();
+
+// Detailed sync check
+const sync = syncCheck();
+console.log(sync.missing); // ['API_KEY', 'SECRET']
+
+// Custom validation
+const errors = validate(process.env, [
+  { key: 'PORT', type: 'port', required: true },
+  { key: 'NODE_ENV', type: 'enum', enum: ['dev', 'staging', 'prod'] },
+]);
+
+// Leak detection
+const leaks = checkLeaks();
+if (leaks.leaks.length > 0) console.warn('Secrets leaked!');
+```
+
+## Why?
+
+- **Missing env vars** crash your app at runtime -> dotenv-guard catches them at startup
+- **Type mismatches** (port as string, URL without protocol) -> dotenv-guard validates
+- **.env committed to git** -> dotenv-guard blocks it with pre-commit hook
+- **Zero dependencies** -> no supply chain risk, tiny bundle
+
+## License
+
+MIT - [Scuton Technology](https://scuton.com)

package/dist/auto.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/auto.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/auto.js

@@ -0,0 +1,81 @@
+"use strict";
+
+// src/core/sync.ts
+var import_fs = require("fs");
+
+// 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;
+}
+
+// src/core/sync.ts
+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/utils/colors.ts
+var isColorSupported = process.env.NO_COLOR === void 0 && process.stdout.isTTY;
+var wrap = (code, resetCode) => (str) => isColorSupported ? `\x1B[${code}m${str}\x1B[${resetCode}m` : str;
+var red = wrap(31, 39);
+var green = wrap(32, 39);
+var yellow = wrap(33, 39);
+var blue = wrap(34, 39);
+var gray = wrap(90, 39);
+var bold = wrap(1, 22);
+var dim = wrap(2, 22);
+
+// src/auto.ts
+try {
+  const result = syncCheck();
+  if (result.missing.length > 0) {
+    console.error("");
+    console.error(red(bold("  \u2716 dotenv-guard: Missing environment variables")));
+    console.error("");
+    for (const key of result.missing) {
+      console.error(yellow(`    \u2192 ${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) {
+  if (!err.message.includes("not found")) {
+    console.warn(yellow(`  \u26A0 dotenv-guard: ${err.message}`));
+  }
+}

package/dist/auto.mjs

@@ -0,0 +1,30 @@
+import {
+  bold,
+  red,
+  yellow
+} from "./chunk-RLNPDDSP.mjs";
+import {
+  syncCheck
+} from "./chunk-YYFNUR7Y.mjs";
+
+// src/auto.ts
+try {
+  const result = syncCheck();
+  if (result.missing.length > 0) {
+    console.error("");
+    console.error(red(bold("  \u2716 dotenv-guard: Missing environment variables")));
+    console.error("");
+    for (const key of result.missing) {
+      console.error(yellow(`    \u2192 ${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) {
+  if (!err.message.includes("not found")) {
+    console.warn(yellow(`  \u26A0 dotenv-guard: ${err.message}`));
+  }
+}

package/dist/chunk-QXZQR35R.mjs

@@ -0,0 +1,222 @@
+import {
+  parseEnvFile
+} from "./chunk-YYFNUR7Y.mjs";
+
+// 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
+import { execSync } from "child_process";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync } from "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 (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    gitignoreHasEnv = content.split("\n").some(
+      (line) => line.trim() === ".env" || line.trim() === ".env*" || line.trim() === ".env.local"
+    );
+  }
+  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 {
+  }
+  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 };
+}
+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
+`;
+  mkdirSync(hookDir, { recursive: true });
+  writeFileSync(hookPath, hookScript, "utf-8");
+  try {
+    chmodSync(hookPath, "755");
+  } catch {
+  }
+}
+
+// src/core/generator.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, appendFileSync } from "fs";
+function generateExample(envPath = ".env", outputPath = ".env.example") {
+  if (!existsSync2(envPath)) throw new Error(`${envPath} not found`);
+  const content = readFileSync2(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";
+  writeFileSync2(outputPath, output, "utf-8");
+  return output;
+}
+function ensureGitignore(dir = ".") {
+  const gitignorePath = `${dir}/.gitignore`;
+  const envEntries = [".env", ".env.local", ".env.*.local"];
+  let content = "";
+  if (existsSync2(gitignorePath)) {
+    content = readFileSync2(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;
+}
+
+export {
+  validate,
+  inferRules,
+  checkLeaks,
+  installPreCommitHook,
+  generateExample,
+  ensureGitignore
+};

package/dist/chunk-RLNPDDSP.mjs

@@ -0,0 +1,19 @@
+// src/utils/colors.ts
+var isColorSupported = process.env.NO_COLOR === void 0 && process.stdout.isTTY;
+var wrap = (code, resetCode) => (str) => isColorSupported ? `\x1B[${code}m${str}\x1B[${resetCode}m` : str;
+var red = wrap(31, 39);
+var green = wrap(32, 39);
+var yellow = wrap(33, 39);
+var blue = wrap(34, 39);
+var gray = wrap(90, 39);
+var bold = wrap(1, 22);
+var dim = wrap(2, 22);
+
+export {
+  red,
+  green,
+  yellow,
+  gray,
+  bold,
+  dim
+};

package/dist/chunk-YYFNUR7Y.mjs

@@ -0,0 +1,54 @@
+// 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
+import { readFileSync, existsSync } from "fs";
+function syncCheck(envPath = ".env", examplePath = ".env.example") {
+  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 = /* @__PURE__ */ new Set();
+  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 };
+}
+
+export {
+  parseEnvFile,
+  parseEnvFileToMap,
+  syncCheck
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node