safe-dotenv-check 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,161 @@
+# safe-dotenv-check
+
+[![CI](https://github.com/eunsujihoon-hub/safe-dotenv-check/actions/workflows/ci.yml/badge.svg)](https://github.com/eunsujihoon-hub/safe-dotenv-check/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+Small CLI to compare required environment keys from a manifest file such as `.env.example` against one or more target `.env` files.
+
+It focuses on the checks that usually break deploys:
+
+- missing required keys
+- empty values for required keys
+- unexpected extra keys
+- optional keys documented directly inside the example manifest
+- machine-readable JSON output for CI or deployment checks
+- a reusable GitHub Action wrapper for repository-level checks
+
+## Install
+
+```bash
+npm install --global safe-dotenv-check
+```
+
+Or run it without installing:
+
+```bash
+npx safe-dotenv-check --example .env.example --env .env
+```
+
+## GitHub Action
+
+Use the repository directly in GitHub Actions:
+
+```yaml
+jobs:
+  env-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: eunsujihoon-hub/safe-dotenv-check@v0.2.0
+        with:
+          example: .env.example
+          env_files: |
+            .env.ci
+            .env.production
+```
+
+Available inputs:
+
+- `example`: manifest path such as `.env.example`
+- `env_files`: newline-separated target env file paths
+- `allow_extra`: set to `true` to ignore keys that exist only in target files
+- `summary`: set to `false` to skip step summary output
+- `json_output_path`: optional path where the JSON report should be copied
+
+## Usage
+
+```bash
+safe-dotenv-check --example .env.example --env .env
+safe-dotenv-check --example .env.example --env .env --env .env.production
+safe-dotenv-check --example .env.example --env .env --allow-extra
+safe-dotenv-check --example .env.example --env .env --format json
+```
+
+## Exit codes
+
+- `0`: all files passed
+- `1`: at least one file has missing or empty required keys
+- `2`: invalid CLI usage or unreadable files
+
+## What counts as required
+
+Every non-comment key in the example file is treated as required.
+
+Example:
+
+```dotenv
+# .env.example
+DATABASE_URL=
+OPENAI_API_KEY=
+LOG_LEVEL=info
+?SENTRY_DSN=
+REDIS_URL= # optional
+```
+
+Optional keys can be marked in either of these forms:
+
+```dotenv
+?SENTRY_DSN=
+REDIS_URL= # optional
+```
+
+## Output example
+
+```text
+PASS .env
+FAIL .env.production
+  missing: OPENAI_API_KEY
+  empty: DATABASE_URL
+  extra: DEBUG
+```
+
+## JSON output
+
+```bash
+safe-dotenv-check --example .env.example --env .env --format json
+```
+
+```json
+{
+  "ok": false,
+  "example": ".env.example",
+  "files": [
+    {
+      "file": ".env",
+      "missing": [
+        "OPENAI_API_KEY"
+      ],
+      "empty": [
+        "DATABASE_URL"
+      ],
+      "extra": [],
+      "optional": [],
+      "ok": false
+    }
+  ]
+}
+```
+
+## Why this exists
+
+Many teams keep `.env.example` around but do not actually verify deploy-time env files against it. This tool is intentionally small enough to drop into CI, pre-deploy scripts, or local sanity checks.
+
+## Secret safety
+
+This repository ignores common secret-bearing files by default:
+
+- `.env`
+- `.env.local`
+- `.env.production.local`
+- `.envrc`
+- `secrets/`
+- certificate and private key files such as `*.pem` and `*.key`
+
+Commit only redacted examples such as `.env.example`. Do not commit real credentials just because the tool checks them.
+
+## Roadmap
+
+- optional support for warning-only keys
+- shell-friendly summary mode
+- GitHub Action wrapper
+
+## Contributing
+
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Development
+
+```bash
+npm test
+npm run pack:check
+```

package/action.yml

@@ -0,0 +1,93 @@
+name: safe-dotenv-check
+description: Validate one or more .env files against a .env.example-style manifest.
+
+inputs:
+  example:
+    description: Path to the manifest file, usually .env.example.
+    required: true
+  env_files:
+    description: Newline-separated target .env file paths to validate.
+    required: true
+  allow_extra:
+    description: Set to true to ignore keys that exist only in target env files.
+    required: false
+    default: "false"
+  summary:
+    description: Set to true to write a markdown summary to the GitHub Actions step summary.
+    required: false
+    default: "true"
+  json_output_path:
+    description: Optional path where the JSON report should be copied.
+    required: false
+    default: ""
+
+outputs:
+  ok:
+    description: Whether all target files passed validation.
+    value: ${{ steps.validate.outputs.ok }}
+  report_path:
+    description: Path to the generated JSON report inside the runner workspace.
+    value: ${{ steps.validate.outputs.report_path }}
+
+runs:
+  using: composite
+  steps:
+    - id: validate
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        report_path="${RUNNER_TEMP}/safe-dotenv-check-report.json"
+        args=(--example "${{ inputs.example }}")
+
+        while IFS= read -r line; do
+          if [ -n "$line" ]; then
+            args+=(--env "$line")
+          fi
+        done <<'EOF'
+        ${{ inputs.env_files }}
+        EOF
+
+        if [ "${{ inputs.allow_extra }}" = "true" ]; then
+          args+=(--allow-extra)
+        fi
+
+        set +e
+        node "${GITHUB_ACTION_PATH}/bin/safe-dotenv-check.js" "${args[@]}" --format json >"${report_path}"
+        status=$?
+        set -e
+
+        ok=false
+        if [ "${status}" -eq 0 ]; then
+          ok=true
+        fi
+
+        echo "ok=${ok}" >>"${GITHUB_OUTPUT}"
+        echo "report_path=${report_path}" >>"${GITHUB_OUTPUT}"
+
+        if [ -n "${{ inputs.json_output_path }}" ]; then
+          mkdir -p "$(dirname "${{ inputs.json_output_path }}")"
+          cp "${report_path}" "${{ inputs.json_output_path }}"
+        fi
+
+        if [ "${{ inputs.summary }}" = "true" ]; then
+          REPORT_PATH="${report_path}" node <<'EOF' >>"${GITHUB_STEP_SUMMARY}"
+        const fs = require("node:fs");
+        const report = JSON.parse(fs.readFileSync(process.env.REPORT_PATH, "utf8"));
+
+        process.stdout.write("## safe-dotenv-check\n\n");
+        process.stdout.write(`Manifest: \`${report.example}\`\n\n`);
+        process.stdout.write("| File | Status | Missing | Empty | Extra |\n");
+        process.stdout.write("| --- | --- | --- | --- | --- |\n");
+
+        for (const item of report.files) {
+          const status = item.ok ? "PASS" : "FAIL";
+          const missing = item.missing.length ? item.missing.join(", ") : "-";
+          const empty = item.empty.length ? item.empty.join(", ") : "-";
+          const extra = item.extra.length ? item.extra.join(", ") : "-";
+          process.stdout.write(`| \`${item.file}\` | ${status} | ${missing} | ${empty} | ${extra} |\n`);
+        }
+          EOF
+        fi
+
+        exit "${status}"

package/bin/safe-dotenv-check.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+const exitCode = runCli(process.argv.slice(2), process.stdout, process.stderr);
+process.exitCode = exitCode;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "safe-dotenv-check",
+  "version": "0.2.1",
+  "description": "Small CLI to verify .env files against a required key manifest.",
+  "type": "module",
+  "homepage": "https://github.com/eunsujihoon-hub/safe-dotenv-check#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eunsujihoon-hub/safe-dotenv-check.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eunsujihoon-hub/safe-dotenv-check/issues"
+  },
+  "bin": {
+    "safe-dotenv-check": "bin/safe-dotenv-check.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "action.yml"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:check"
+  },
+  "keywords": [
+    "dotenv",
+    "env",
+    "cli",
+    "validation",
+    "developer-tools"
+  ],
+  "author": "eunsujihoon-hub",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/check.js

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+
+export function parseEnvFile(content) {
+  const entries = new Map();
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const withoutExport = line.startsWith("export ") ? line.slice(7) : line;
+    const separatorIndex = withoutExport.indexOf("=");
+    const key = separatorIndex === -1
+      ? withoutExport.trim()
+      : withoutExport.slice(0, separatorIndex).trim();
+
+    if (!key) {
+      continue;
+    }
+
+    const value = separatorIndex === -1 ? "" : withoutExport.slice(separatorIndex + 1).trim();
+    entries.set(key, stripWrappingQuotes(value));
+  }
+
+  return entries;
+}
+
+export function parseExampleFile(content) {
+  const requiredEntries = new Map();
+  const optionalEntries = new Map();
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const withoutExport = line.startsWith("export ") ? line.slice(7) : line;
+    const optional = /(^\?[\w.-]+\s*=)|(\s+#\s*optional\s*$)/i.test(withoutExport);
+    const normalizedLine = withoutExport
+      .replace(/^\?/, "")
+      .replace(/\s+#\s*optional\s*$/i, "");
+
+    const separatorIndex = normalizedLine.indexOf("=");
+    const key = separatorIndex === -1
+      ? normalizedLine.trim()
+      : normalizedLine.slice(0, separatorIndex).trim();
+
+    if (!key) {
+      continue;
+    }
+
+    const value = separatorIndex === -1 ? "" : normalizedLine.slice(separatorIndex + 1).trim();
+    const targetMap = optional ? optionalEntries : requiredEntries;
+    targetMap.set(key, stripWrappingQuotes(value));
+  }
+
+  return {
+    requiredEntries,
+    optionalEntries,
+    allEntries: new Map([...requiredEntries, ...optionalEntries])
+  };
+}
+
+function stripWrappingQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === "\"" && last === "\"") || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+
+  return value;
+}
+
+export function loadEnvFile(filePath) {
+  return parseEnvFile(fs.readFileSync(filePath, "utf8"));
+}
+
+export function loadExampleFile(filePath) {
+  return parseExampleFile(fs.readFileSync(filePath, "utf8"));
+}
+
+export function compareEnv(exampleEntries, targetEntries, options = {}) {
+  const exampleSpec = normalizeExampleSpec(exampleEntries);
+  const requiredKeys = [...exampleSpec.requiredEntries.keys()];
+  const targetKeys = new Set(targetEntries.keys());
+  const missing = [];
+  const empty = [];
+  const optional = [...exampleSpec.optionalEntries.keys()].sort();
+
+  for (const key of requiredKeys) {
+    if (!targetKeys.has(key)) {
+      missing.push(key);
+      continue;
+    }
+
+    if (targetEntries.get(key) === "") {
+      empty.push(key);
+    }
+  }
+
+  const extra = options.allowExtra
+    ? []
+    : [...targetKeys].filter((key) => !exampleSpec.allEntries.has(key)).sort();
+
+  return {
+    missing,
+    empty,
+    extra,
+    optional,
+    ok: missing.length === 0 && empty.length === 0 && extra.length === 0
+  };
+}
+
+function normalizeExampleSpec(exampleEntries) {
+  if (exampleEntries?.requiredEntries && exampleEntries?.optionalEntries && exampleEntries?.allEntries) {
+    return exampleEntries;
+  }
+
+  return {
+    requiredEntries: exampleEntries,
+    optionalEntries: new Map(),
+    allEntries: exampleEntries
+  };
+}

package/src/cli.js

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+import { compareEnv, loadEnvFile, loadExampleFile } from "./check.js";
+
+const HELP_TEXT = `safe-dotenv-check
+
+Usage:
+  safe-dotenv-check --example .env.example --env .env
+  safe-dotenv-check --example .env.example --env .env --env .env.production
+  safe-dotenv-check --example .env.example --env .env --allow-extra
+  safe-dotenv-check --example .env.example --env .env --format json
+
+Options:
+  --example <path>    Required manifest file, usually .env.example
+  --env <path>        Target .env file to verify, repeatable
+  --allow-extra       Ignore keys that exist only in target files
+  --format <type>     Output format: text or json
+  --help              Show this message
+
+Example optional keys:
+  ?SENTRY_DSN=
+  REDIS_URL= # optional
+`;
+
+export function runCli(argv, stdout, stderr) {
+  const parsed = parseArgs(argv);
+
+  if (parsed.help) {
+    stdout.write(`${HELP_TEXT}\n`);
+    return 0;
+  }
+
+  if (parsed.error) {
+    stderr.write(`error: ${parsed.error}\n`);
+    stderr.write("run with --help for usage\n");
+    return 2;
+  }
+
+  try {
+    const exampleEntries = loadExampleFile(parsed.examplePath);
+    let allOk = true;
+    const reports = [];
+
+    for (const envPath of parsed.envPaths) {
+      const targetEntries = loadEnvFile(envPath);
+      const result = compareEnv(exampleEntries, targetEntries, {
+        allowExtra: parsed.allowExtra
+      });
+      reports.push({
+        file: envPath,
+        ...result
+      });
+
+      if (!result.ok) {
+        allOk = false;
+      }
+    }
+
+    if (parsed.format === "json") {
+      stdout.write(`${JSON.stringify({
+        ok: allOk,
+        example: parsed.examplePath,
+        files: reports
+      }, null, 2)}\n`);
+    } else {
+      for (const report of reports) {
+        if (report.ok) {
+          stdout.write(`PASS ${report.file}\n`);
+          continue;
+        }
+
+        stdout.write(`FAIL ${report.file}\n`);
+        writeList(stdout, "missing", report.missing);
+        writeList(stdout, "empty", report.empty);
+        writeList(stdout, "extra", report.extra);
+        writeList(stdout, "optional", report.optional);
+      }
+    }
+
+    return allOk ? 0 : 1;
+  } catch (error) {
+    stderr.write(`error: ${error.message}\n`);
+    return 2;
+  }
+}
+
+function parseArgs(argv) {
+  const envPaths = [];
+  let examplePath = "";
+  let allowExtra = false;
+  let format = "text";
+  let help = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+
+    if (arg === "--allow-extra") {
+      allowExtra = true;
+      continue;
+    }
+
+    if (arg === "--format") {
+      format = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--example") {
+      examplePath = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--env") {
+      const envPath = argv[index + 1] ?? "";
+      envPaths.push(envPath);
+      index += 1;
+      continue;
+    }
+
+    return { error: `unknown argument: ${arg}` };
+  }
+
+  if (!help) {
+    if (!examplePath) {
+      return { error: "--example is required" };
+    }
+
+    if (envPaths.length === 0) {
+      return { error: "at least one --env is required" };
+    }
+
+    if (!["text", "json"].includes(format)) {
+      return { error: "--format must be either text or json" };
+    }
+
+    const filePaths = [examplePath, ...envPaths];
+    for (const filePath of filePaths) {
+      if (!filePath) {
+        return { error: "missing value for --example or --env" };
+      }
+
+      const resolvedPath = path.resolve(filePath);
+      if (!fs.existsSync(resolvedPath)) {
+        return { error: `file not found: ${filePath}` };
+      }
+    }
+  }
+
+  return {
+    allowExtra,
+    envPaths,
+    examplePath,
+    format,
+    help
+  };
+}
+
+function writeList(stdout, label, values) {
+  if (values.length > 0) {
+    stdout.write(`  ${label}: ${values.join(", ")}\n`);
+  }
+}