@webbuilder135/envsentinel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBuilder135
+
+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,9 @@
+# envsentinel
+
+Audit `.env` against a required env file (typically `.env.example`). Optionally scans your repo for env usage (best-effort) and reports missing/empty/extra keys. CI-friendly exit codes.
+
+## Install
+
+```bash
+npm i envsentinel
+

package/bin/envsentinel.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli.js";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@webbuilder135/envsentinel",
+  "version": "0.1.0",
+  "description": "Audit .env against a required env file (.env.example). CI-friendly.",
+  "type": "module",
+  "bin": "./bin/envsentinel.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "node -c bin/envsentinel.js && node -c src/cli.js && node -c src/index.js"
+  },
+  "keywords": ["dotenv", "env", "config", "ci", "audit", "lint"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { auditProject, proReportHtml } from "./index.js";
+
+function parseArgs(argv) {
+  const args = { root: process.cwd(), json: false, verbose: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const v = argv[i + 1];
+
+    if (a === "--env") {
+      args.env = v; i++;
+    } else if (a === "--required") {
+      args.required = v; i++;
+    } else if (a === "--root") {
+      args.root = v; i++;
+    } else if (a === "--json") {
+      args.json = true;
+    } else if (a === "--html") {
+      args.html = v; i++;
+    } else if (a === "--verbose" || a === "-v") {
+      args.verbose = true;
+    } else if (a === "-h" || a === "--help") {
+      args.help = true;
+    } else {
+      args.unknown ??= [];
+      args.unknown.push(a);
+    }
+  }
+  return args;
+}
+
+function usage() {
+  console.log(`
+envsentinel --env .env --required .env.example [--root .] [--json] [--html report.html] [--verbose]
+
+Options:
+  --env <path>         Path to .env file
+  --required <path>    Path to required env file (e.g. .env.example)
+  --root <dir>         Repo root to scan for env usage (default: cwd)
+  --json               Print full JSON result
+  --verbose, -v        Print additional hints (UnusedRequired)
+  --html <path>        (Pro) Write HTML report
+
+Exit codes:
+  0 = OK
+  1 = missing required keys OR empty required values
+  2 = invalid args / missing files / runtime error
+`.trim());
+}
+
+function ensureFile(p, label) {
+  if (!p) throw new Error(`Missing ${label}`);
+  if (!fs.existsSync(p)) throw new Error(`File not found: ${p}`);
+  return path.resolve(p);
+}
+
+function printHuman(r, { verbose }) {
+  const line = (k, arr) => console.log(`${k}: ${arr.length ? arr.join(", ") : "-"}`);
+  line("Missing", r.missing);
+  line("Empty", r.empty);
+  line("Extra", r.extra);
+  if (verbose) line("UnusedRequired", r.unusedRequired);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  if (args.unknown?.length) {
+    console.error(`Unknown args: ${args.unknown.join(", ")}`);
+    usage();
+    process.exit(2);
+  }
+
+  try {
+    const envPath = ensureFile(args.env, "--env");
+    const requiredPath = ensureFile(args.required, "--required");
+    const rootDir = path.resolve(args.root);
+
+    const result = await auditProject({ envPath, requiredPath, rootDir });
+
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else printHuman(result, { verbose: args.verbose });
+
+    if (args.html) {
+      const html = await proReportHtml(result);
+      fs.writeFileSync(args.html, html, "utf8");
+      console.log(`Wrote ${args.html}`);
+    }
+
+    const bad = result.missing.length > 0 || result.empty.length > 0;
+    process.exit(bad ? 1 : 0);
+  } catch (err) {
+    console.error(String(err?.message ?? err));
+    process.exit(2);
+  }
+}
+
+main();

package/src/env/audit.js

@@ -0,0 +1,27 @@
+export function auditEnv({ requiredKeys, envMap, repoUsedKeys = [] }) {
+  const required = new Set(requiredKeys);
+  const present = new Set(envMap.keys());
+  const used = new Set(repoUsedKeys);
+
+  const missing = [...required].filter((k) => !present.has(k)).sort();
+
+  const empty = [...required]
+    .filter((k) => present.has(k))
+    .filter((k) => (envMap.get(k) ?? "").trim() === "")
+    .sort();
+
+  const extra = [...present].filter((k) => !required.has(k)).sort();
+
+  // "required but not used anywhere in repo" (useful hint)
+  const unusedRequired = [...required].filter((k) => present.has(k) && !used.has(k)).sort();
+
+  return {
+    required: [...required].sort(),
+    present: [...present].sort(),
+    used: [...used].sort(),
+    missing,
+    empty,
+    extra,
+    unusedRequired
+  };
+}

package/src/env/parseEnvFile.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+
+export function parseEnvContent(content) {
+  const map = new Map();
+  const lines = content.split(/\r?\n/);
+
+  for (let line of lines) {
+    line = line.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    // support: export KEY=VALUE
+    if (line.startsWith("export ")) line = line.slice(7).trim();
+
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+
+    // strip inline comment only if unquoted
+    const isQuoted =
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"));
+
+    if (!isQuoted) {
+      // remove " #comment" style
+      const idx = value.indexOf(" #");
+      if (idx !== -1) value = value.slice(0, idx).trim();
+      if (value.startsWith("#")) value = "";
+    }
+
+    // unquote
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    // minimal escapes (double quotes common)
+    value = value
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t")
+      .replace(/\\"/g, '"');
+
+    if (key) map.set(key, value);
+  }
+
+  return map;
+}
+
+export function parseEnvFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  return parseEnvContent(content);
+}

package/src/env/scanRepo.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  "coverage"
+]);
+
+// Intentionally exclude .md and .env* to reduce false positives from docs/examples.
+const DEFAULT_EXT_RE = /\.(js|cjs|mjs|ts|tsx|jsx|json|yml|yaml|sh|ps1|toml|ini)$/i;
+
+export function scanRepoForEnvUsage(rootDir, { ignoreDirs = DEFAULT_IGNORE_DIRS } = {}) {
+  const used = new Set();
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (ignoreDirs.has(entry.name)) continue;
+        walk(full);
+        continue;
+      }
+
+      // skip dotenv files explicitly
+      if (entry.name === ".env" || entry.name.startsWith(".env.")) continue;
+
+      if (!DEFAULT_EXT_RE.test(entry.name)) continue;
+
+      let text;
+      try {
+        text = fs.readFileSync(full, "utf8");
+      } catch {
+        continue;
+      }
+
+      for (const m of text.matchAll(/\bprocess\.env\.([A-Z0-9_]+)\b/g)) {
+        used.add(m[1]);
+      }
+
+      for (const m of text.matchAll(/\bprocess\.env\[(["'])([A-Z0-9_]+)\1\]/g)) {
+        used.add(m[2]);
+      }
+
+      for (const m of text.matchAll(/\$\{([A-Z][A-Z0-9_]{2,})\}/g)) {
+        used.add(m[1]);
+      }
+    }
+  }
+
+  walk(rootDir);
+  return [...used].sort();
+}

package/src/index.js

@@ -0,0 +1,28 @@
+import { parseEnvFile } from "./env/parseEnvFile.js";
+import { scanRepoForEnvUsage } from "./env/scanRepo.js";
+import { auditEnv } from "./env/audit.js";
+import { loadPro } from "./pro-loader.js";
+
+export { parseEnvFile, scanRepoForEnvUsage, auditEnv };
+
+export async function auditProject({ envPath, requiredPath, rootDir = process.cwd() }) {
+  const required = parseEnvFile(requiredPath);
+  const env = parseEnvFile(envPath);
+  const usedKeys = scanRepoForEnvUsage(rootDir);
+
+  return auditEnv({
+    requiredKeys: [...required.keys()],
+    envMap: env,
+    repoUsedKeys: usedKeys
+  });
+}
+
+export async function proReportHtml(auditResult) {
+  const pro = await loadPro();
+  if (!pro?.proReportHtml) {
+    throw new Error(
+      "Pro not available: install pro.js next to package root (node_modules/envsentinel/pro.js)."
+    );
+  }
+  return pro.proReportHtml(auditResult);
+}

package/src/pro-loader.js

@@ -0,0 +1,14 @@
+export async function loadPro() {
+  try {
+    const mod = await import("../pro.js");
+    return mod?.default ?? mod;
+  } catch (err) {
+    if (
+      err?.code === "ERR_MODULE_NOT_FOUND" ||
+      err?.code === "MODULE_NOT_FOUND"
+    ) {
+      return null;
+    }
+    throw err;
+  }
+}