fouad-env-guardian 0.1.1

package/README.md

@@ -0,0 +1,61 @@
+# `fouad-env-guardian`
+
+CLI tool to scan projects for unsafe `.env` practices and likely secret exposure mistakes.
+
+## Package and command
+
+- npm package: `fouad-env-guardian`
+- CLI command: `env-guardian`
+
+## Install from npm
+
+```bash
+npm install -g fouad-env-guardian
+env-guardian
+```
+
+## Usage
+
+```bash
+env-guardian
+env-guardian --version
+env-guardian --help
+```
+
+## What it checks
+
+- Whether `.env` exists
+- Whether `.env` is tracked by git
+- Whether `.env.example` exists
+- Whether `.env` contains common secret-like variable names such as `API_KEY`, `SECRET`, `TOKEN`, `PASSWORD`, or `PRIVATE_KEY`
+
+## Example output
+
+```text
+Env Guardian Report
+
+Project: C:\my-project
+- .env exists: yes
+- .env tracked by git: yes
+- .env.example exists: no
+- secret-like keys found: API_KEY, TOKEN
+
+Warnings:
+- The .env file is tracked by git.
+- Missing .env.example.
+- Potential secret variable detected: API_KEY
+- Potential secret variable detected: TOKEN
+```
+
+## Notes
+
+- Run the command from the project root you want to inspect.
+- The tool exits with a non-zero code when warnings are found, which makes it useful in CI.
+- Detection is intentionally conservative and should be treated as a warning signal, not proof of a leak.
+
+## Roadmap
+
+- Auto-fix suggestions for `.gitignore`
+- Framework-aware checks for Next.js, Vite, and similar tools
+- Configurable secret patterns and ignore rules
+- CI examples and GitHub Actions integration

package/cli/index.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import chalk from "chalk";
+import { createRequire } from "module";
+import { scanEnv } from "../core/scan-env.mjs";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(chalk.bold("env-guardian"));
+  console.log("Scan the current project for unsafe .env practices.\n");
+  console.log(chalk.gray("Usage:"));
+  console.log("  env-guardian");
+  console.log("  env-guardian --version");
+  process.exit(0);
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(version);
+  process.exit(0);
+}
+
+try {
+  const result = scanEnv();
+
+  console.log(chalk.cyan("\nEnv Guardian Report\n"));
+  console.log(`Project: ${result.projectRoot}`);
+  console.log(`- .env exists: ${result.hasEnv ? "yes" : "no"}`);
+  console.log(`- .env tracked by git: ${result.envTracked ? "yes" : "no"}`);
+  console.log(`- .env.example exists: ${result.hasExample ? "yes" : "no"}`);
+
+  if (result.detectedSecrets.length > 0) {
+    console.log(`- secret-like keys found: ${result.detectedSecrets.join(", ")}`);
+  }
+
+  if (result.warnings.length > 0) {
+    console.log(chalk.yellow("\nWarnings:"));
+    for (const warning of result.warnings) {
+      console.log(chalk.yellow(`- ${warning}`));
+    }
+    process.exitCode = 1;
+  } else {
+    console.log(chalk.green("\nNo issues found"));
+  }
+} catch (err) {
+  console.error(chalk.red(err?.message || String(err)));
+  process.exit(1);
+}

package/core/scan-env.mjs

@@ -0,0 +1,82 @@
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+
+const DEFAULT_SECRET_PATTERNS = [
+  { name: "API_KEY", regex: /^\s*[A-Z0-9_]*API[_-]?KEY\s*=/im },
+  { name: "SECRET", regex: /^\s*[A-Z0-9_]*SECRET\s*=/im },
+  { name: "TOKEN", regex: /^\s*[A-Z0-9_]*TOKEN\s*=/im },
+  { name: "PASSWORD", regex: /^\s*[A-Z0-9_]*PASSWORD\s*=/im },
+  { name: "PRIVATE_KEY", regex: /^\s*[A-Z0-9_]*PRIVATE[_-]?KEY\s*=/im },
+];
+
+function isGitTracked(projectRoot, relativePath) {
+  try {
+    const result = execFileSync("git", ["ls-files", "--cached", "--full-name", relativePath], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+
+    return result.includes(relativePath);
+  } catch (error) {
+    const stderr = String(error?.stderr || "");
+    if (
+      stderr.includes("not a git repository") ||
+      stderr.includes("fatal: not a git repository") ||
+      stderr.includes("did not match any files")
+    ) {
+      return false;
+    }
+
+    return false;
+  }
+}
+
+function detectSecrets(content) {
+  const findings = [];
+
+  for (const pattern of DEFAULT_SECRET_PATTERNS) {
+    if (pattern.regex.test(content)) {
+      findings.push(pattern.name);
+    }
+  }
+
+  return findings;
+}
+
+export function scanEnv(projectRoot = process.cwd(), options = {}) {
+  const gitTrackedChecker = options.gitTrackedChecker || isGitTracked;
+  const envPath = path.join(projectRoot, ".env");
+  const examplePath = path.join(projectRoot, ".env.example");
+
+  const result = {
+    projectRoot,
+    hasEnv: fs.existsSync(envPath),
+    envTracked: false,
+    hasExample: fs.existsSync(examplePath),
+    warnings: [],
+    detectedSecrets: [],
+  };
+
+  if (result.hasEnv) {
+    result.envTracked = gitTrackedChecker(projectRoot, ".env");
+
+    if (result.envTracked) {
+      result.warnings.push("The .env file is tracked by git.");
+    }
+
+    const content = fs.readFileSync(envPath, "utf8");
+    result.detectedSecrets = detectSecrets(content);
+
+    for (const finding of result.detectedSecrets) {
+      result.warnings.push(`Potential secret variable detected: ${finding}`);
+    }
+  }
+
+  if (!result.hasExample) {
+    result.warnings.push("Missing .env.example.");
+  }
+
+  return result;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "fouad-env-guardian",
+  "version": "0.1.1",
+  "description": "CLI tool to scan projects for unsafe .env practices and likely secret exposure mistakes.",
+  "author": "Fouad",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "env",
+    "dotenv",
+    "security",
+    "secrets",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FouadBechar/NextApp.git",
+    "directory": "tools/env-guardian"
+  },
+  "homepage": "https://github.com/FouadBechar/NextApp/tree/main/tools/env-guardian",
+  "bugs": {
+    "url": "https://github.com/FouadBechar/NextApp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "cli",
+    "core",
+    "README.md"
+  ],
+  "bin": {
+    "env-guardian": "cli/index.mjs"
+  },
+  "scripts": {
+    "help": "node ./cli/index.mjs --help",
+    "test": "node ./tests/run-tests.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2"
+  }
+}