@kevinpatil/envguard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Patil
+
+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,125 @@
+# @kevinpatil/envguard
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/kevinpatildxd/envguard/actions/workflows/ci.yml/badge.svg)](https://github.com/kevinpatildxd/envguard/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40kevinpatil%2Fenvguard.svg)](https://www.npmjs.com/package/@kevinpatil/envguard)
+[![npm downloads](https://img.shields.io/npm/dm/%40kevinpatil%2Fenvguard.svg)](https://www.npmjs.com/package/@kevinpatil/envguard)
+
+Validate your `.env` file against `.env.example` before your app ships.
+
+Catches missing keys, insecure defaults, type mismatches, weak secrets, and more — in a single fast command.
+
+```
+$ npx @kevinpatil/envguard
+
+envguard — checking .env against .env.example
+
+ERRORS (2)
+  ✗ DATABASE_URL — Missing required key (defined in .env.example)
+  ✗ JWT_SECRET — Insecure placeholder value: 'secret'
+
+WARNINGS (2)
+  ⚠ PORT — Expected a number but got 'abc'
+  ⚠ STRIPE_KEY — Key is not declared in .env.example
+
+2 error(s) found. Fix them before deploying.
+```
+
+---
+
+## Install
+
+```bash
+npm install --save-dev @kevinpatil/envguard
+```
+
+Or run without installing:
+
+```bash
+npx @kevinpatil/envguard
+```
+
+---
+
+## Usage
+
+```bash
+# Validate .env against .env.example in the current directory
+npx @kevinpatil/envguard
+
+# Target a specific env file
+npx @kevinpatil/envguard --env .env.production
+
+# Use a custom example file
+npx @kevinpatil/envguard --example .env.example.production
+
+# Exit with code 1 if any errors are found (for CI)
+npx @kevinpatil/envguard --strict
+
+# Output results as JSON
+npx @kevinpatil/envguard --json
+```
+
+---
+
+## Validation Rules
+
+| Rule | Severity | Description |
+|---|---|---|
+| `missing-key` | ERROR | Key defined in `.env.example` is absent from `.env` |
+| `empty-value` | ERROR | Key is present but has no value |
+| `insecure-defaults` | ERROR | Value matches a known insecure placeholder (`changeme`, `secret`, `todo`…) |
+| `undeclared-key` | WARNING | Key exists in `.env` but is not in `.env.example` |
+| `weak-secret` | WARNING | Secret key is under 16 characters |
+| `type-mismatch` | WARNING | Numeric key (`PORT`, `TIMEOUT`…) has a non-numeric value |
+| `malformed-url` | WARNING | URL key has a value with a missing or unrecognized protocol |
+| `boolean-mismatch` | WARNING | Boolean key (`FEATURE_*`, `ENABLE_*`…) has a non-boolean value |
+
+---
+
+## CI Integration
+
+Add envguard to your pipeline to block deployments with bad config:
+
+### GitHub Actions
+
+```yaml
+- name: Validate environment variables
+  run: npx @kevinpatil/envguard --strict
+```
+
+### Any CI
+
+```bash
+npx @kevinpatil/envguard --strict  # exits with code 1 if errors are found
+```
+
+### JSON output for custom pipelines
+
+```bash
+npx @kevinpatil/envguard --json | jq '.[] | select(.severity == "error")'
+```
+
+---
+
+## How it works
+
+1. Reads `.env.example` as the source of truth
+2. Reads your `.env` file
+3. Runs all validation rules against both
+4. Prints a color-coded report to the terminal
+5. In `--strict` mode, exits with code `1` if any errors are found
+
+No config files required. No API keys. Works offline, in Docker, everywhere.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT © [Kevin Patil](https://github.com/kevinpatildxd)

package/dist/index.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_commander = require("commander");
+var import_path = __toESM(require("path"));
+
+// src/parser.ts
+var import_fs = __toESM(require("fs"));
+function parseLines(content) {
+  const map = /* @__PURE__ */ new Map();
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = line.slice(0, eqIndex).trim();
+    if (!key) continue;
+    let value = line.slice(eqIndex + 1).trim();
+    const commentIndex = value.indexOf(" #");
+    if (commentIndex !== -1) {
+      value = value.slice(0, commentIndex).trim();
+    }
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    map.set(key, value);
+  }
+  return map;
+}
+function parseEnvFile(filePath) {
+  if (!import_fs.default.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  const content = import_fs.default.readFileSync(filePath, "utf-8");
+  return parseLines(content);
+}
+function parseEnvExample(filePath) {
+  if (!import_fs.default.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  const content = import_fs.default.readFileSync(filePath, "utf-8");
+  return parseLines(content);
+}
+
+// src/rules/missing-key.ts
+function missingKey(env, example) {
+  const results = [];
+  for (const key of example.keys()) {
+    if (!env.has(key)) {
+      results.push({
+        rule: "missing-key",
+        severity: "error",
+        key,
+        message: `Missing required key (defined in .env.example)`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/empty-value.ts
+function emptyValue(env, example) {
+  const results = [];
+  for (const key of example.keys()) {
+    if (env.has(key) && env.get(key) === "") {
+      results.push({
+        rule: "empty-value",
+        severity: "error",
+        key,
+        message: `Value is empty`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/undeclared-key.ts
+function undeclaredKey(env, example) {
+  const results = [];
+  for (const key of env.keys()) {
+    if (!example.has(key)) {
+      results.push({
+        rule: "undeclared-key",
+        severity: "warning",
+        key,
+        message: `Key is not declared in .env.example`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/insecure-defaults.ts
+var INSECURE_VALUES = /* @__PURE__ */ new Set([
+  "changeme",
+  "change_me",
+  "todo",
+  "secret",
+  "password",
+  "1234",
+  "12345",
+  "123456",
+  "test",
+  "example",
+  "placeholder",
+  "dummy",
+  "fake",
+  "temp"
+]);
+function insecureDefaults(env, _example) {
+  const results = [];
+  for (const [key, value] of env.entries()) {
+    if (INSECURE_VALUES.has(value.toLowerCase())) {
+      results.push({
+        rule: "insecure-defaults",
+        severity: "error",
+        key,
+        message: `Insecure placeholder value: '${value}'`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/weak-secret.ts
+var SECRET_PATTERN = /(_SECRET|_KEY|_TOKEN|_PASSWORD|_PASS|_PWD|^JWT_|^API_)/i;
+var MIN_LENGTH = 16;
+function weakSecret(env, _example) {
+  const results = [];
+  for (const [key, value] of env.entries()) {
+    if (SECRET_PATTERN.test(key) && value.length > 0 && value.length < MIN_LENGTH) {
+      results.push({
+        rule: "weak-secret",
+        severity: "warning",
+        key,
+        message: `Secret is too short (${value.length} chars, minimum is ${MIN_LENGTH})`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/type-mismatch.ts
+var NUMERIC_PATTERN = /^(PORT|TIMEOUT|MAX_|MIN_|LIMIT|RETRY_|WORKERS|THREADS)/i;
+function typeMismatch(env, _example) {
+  const results = [];
+  for (const [key, value] of env.entries()) {
+    if (NUMERIC_PATTERN.test(key) && value !== "" && isNaN(Number(value))) {
+      results.push({
+        rule: "type-mismatch",
+        severity: "warning",
+        key,
+        message: `Expected a number but got '${value}'`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/malformed-url.ts
+var URL_PATTERN = /(_URL|_URI|_HOST|^DATABASE_|^REDIS_|^MONGO_)/i;
+var VALID_PROTOCOLS = /* @__PURE__ */ new Set([
+  "http:",
+  "https:",
+  "postgres:",
+  "postgresql:",
+  "mysql:",
+  "mongodb:",
+  "mongodb+srv:",
+  "redis:",
+  "rediss:",
+  "amqp:",
+  "amqps:",
+  "ftp:",
+  "ftps:"
+]);
+function isValidUrl(value) {
+  try {
+    const url = new URL(value);
+    return VALID_PROTOCOLS.has(url.protocol);
+  } catch {
+    return false;
+  }
+}
+function malformedUrl(env, _example) {
+  const results = [];
+  for (const [key, value] of env.entries()) {
+    if (URL_PATTERN.test(key) && value !== "" && !isValidUrl(value)) {
+      results.push({
+        rule: "malformed-url",
+        severity: "warning",
+        key,
+        message: `Value does not appear to be a valid URL: '${value}'`
+      });
+    }
+  }
+  return results;
+}
+
+// src/rules/boolean-mismatch.ts
+var BOOLEAN_PATTERN = /^(FEATURE_|ENABLE_|DISABLE_|IS_|USE_|ALLOW_|FLAG_)/i;
+var VALID_BOOLEANS = /* @__PURE__ */ new Set(["true", "false", "1", "0"]);
+function booleanMismatch(env, _example) {
+  const results = [];
+  for (const [key, value] of env.entries()) {
+    if (BOOLEAN_PATTERN.test(key) && value !== "" && !VALID_BOOLEANS.has(value.toLowerCase())) {
+      results.push({
+        rule: "boolean-mismatch",
+        severity: "warning",
+        key,
+        message: `Expected a boolean (true/false/1/0) but got '${value}'`
+      });
+    }
+  }
+  return results;
+}
+
+// src/validator.ts
+function validate(env, example) {
+  return [
+    ...missingKey(env, example),
+    ...emptyValue(env, example),
+    ...undeclaredKey(env, example),
+    ...insecureDefaults(env, example),
+    ...weakSecret(env, example),
+    ...typeMismatch(env, example),
+    ...malformedUrl(env, example),
+    ...booleanMismatch(env, example)
+  ];
+}
+
+// src/reporter.ts
+var import_chalk = __toESM(require("chalk"));
+function report(results, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  const errors = results.filter((r) => r.severity === "error");
+  const warnings = results.filter((r) => r.severity === "warning");
+  const passedCount = results.length === 0 ? "all checks" : "remaining keys";
+  console.log(import_chalk.default.bold("\nenvguard \u2014 checking .env against .env.example\n"));
+  if (errors.length > 0) {
+    console.log(import_chalk.default.red.bold(`ERRORS (${errors.length})`));
+    for (const r of errors) {
+      console.log(import_chalk.default.red(`  \u2717 ${r.key} \u2014 ${r.message}`));
+    }
+    console.log();
+  }
+  if (warnings.length > 0) {
+    console.log(import_chalk.default.yellow.bold(`WARNINGS (${warnings.length})`));
+    for (const r of warnings) {
+      console.log(import_chalk.default.yellow(`  \u26A0 ${r.key} \u2014 ${r.message}`));
+    }
+    console.log();
+  }
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log(import_chalk.default.green.bold("  \u2714 All checks passed"));
+  } else {
+    console.log(import_chalk.default.green(`PASSED \u2014 ${passedCount} ok`));
+  }
+  console.log();
+  if (errors.length > 0) {
+    console.log(import_chalk.default.red.bold(`${errors.length} error(s) found. Fix them before deploying.`));
+  } else if (warnings.length > 0) {
+    console.log(import_chalk.default.yellow(`${warnings.length} warning(s). Review before deploying.`));
+  }
+}
+
+// src/index.ts
+var program = new import_commander.Command();
+program.name("envguard").description("Validate .env files against .env.example before your app ships").version("1.0.0").option("--env <file>", "path to .env file", ".env").option("--example <file>", "path to .env.example file", ".env.example").option("--strict", "exit with code 1 if any errors are found").option("--json", "output results as JSON").action((options) => {
+  const envPath = import_path.default.resolve(process.cwd(), options.env);
+  const examplePath = import_path.default.resolve(process.cwd(), options.example);
+  const env = parseEnvFile(envPath);
+  const example = parseEnvExample(examplePath);
+  const results = validate(env, example);
+  report(results, { json: options.json });
+  const hasErrors = results.some((r) => r.severity === "error");
+  if (options.strict && hasErrors) {
+    process.exit(1);
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kevinpatil/envguard",
+  "version": "1.0.0",
+  "description": "CLI tool that validates .env files against .env.example before your app ships",
+  "main": "dist/index.js",
+  "bin": {
+    "envguard": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsup --watch"
+  },
+  "keywords": [
+    "cli",
+    "dotenv",
+    "env",
+    "environment-variables",
+    "validation",
+    "devtools",
+    "typescript"
+  ],
+  "author": "Kevin Patil",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevinpatildxd/envguard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kevinpatildxd/envguard/issues"
+  },
+  "homepage": "https://github.com/kevinpatildxd/envguard#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}