@anhuijie/envguard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnvGuard Contributors
+
+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,444 @@
+<div align="center">
+
+# 🛡️ EnvGuard
+
+**Environment Variable Validation, Security Scanning & Documentation Generator**
+
+[![CI](https://github.com/AnhuiJie/envguard/actions/workflows/ci.yml/badge.svg)](https://github.com/AnhuiJie/envguard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)
+
+[English](#english) · [中文](#中文) · [日本語](#日本語)
+
+</div>
+
+---
+
+<a id="english"></a>
+
+## 🇬🇧 English
+
+### Why EnvGuard?
+
+Misconfigured environment variables are a leading cause of production incidents. EnvGuard provides a **single tool** to validate, secure, and document your project's configuration — catching errors before they reach production.
+
+### Features
+
+- **Schema Validation** — Define types, required fields, enums, ranges, and patterns for every variable
+- **Security Scanning** — Detect accidentally committed secrets (AWS keys, GitHub tokens, private keys, etc.)
+- **Auto Documentation** — Generate `.env.example` and markdown docs from your schema
+- **Environment Diff** — Compare `.env` files across dev/staging/prod to find drift
+- **CI/CD Ready** — Exit codes and GitHub Action integration for automated checks
+- **Zero Dependencies** — Pure Node.js, no external packages required
+- **Multi-format Support** — Works with `.env`, `.env.local`, `.env.production`, and more
+
+### Quick Start
+
+```bash
+# Install
+npm install -g envguard
+
+# Create config
+envguard init
+
+# Validate environment variables
+envguard validate
+
+# Scan for secrets
+envguard check
+
+# Generate documentation
+envguard docs
+
+# Compare environments
+envguard diff .env.development .env.production
+```
+
+### Configuration
+
+Create `envguard.config.js` in your project root:
+
+```js
+module.exports = {
+  schema: {
+    NODE_ENV: {
+      required: true,
+      type: 'string',
+      enum: ['development', 'staging', 'production', 'test'],
+      description: 'Application environment',
+    },
+    PORT: {
+      required: false,
+      type: 'port',
+      default: '3000',
+      description: 'Server port',
+    },
+    DATABASE_URL: {
+      required: true,
+      type: 'url',
+      description: 'Database connection string',
+    },
+    JWT_SECRET: {
+      required: true,
+      type: 'string',
+      description: 'Secret key for JWT signing',
+    },
+  },
+  security: {
+    minSeverity: 'medium',
+    ignoreKeys: [],
+  },
+};
+```
+
+### Supported Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Any string value | `any text` |
+| `number` | Numeric value with optional min/max | `42` |
+| `boolean` | true/false, 1/0, yes/no | `true` |
+| `url` | Valid URL | `https://example.com` |
+| `email` | Valid email address | `user@example.com` |
+| `port` | Valid port number (0-65535) | `3000` |
+| `json` | Valid JSON string | `'{"key":"value"}'` |
+| `regex` | Valid regex pattern | `^\\d+$` |
+
+### Rule Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `required` | boolean | Variable must be set |
+| `type` | string | Value type validation |
+| `default` | any | Default value if not set |
+| `enum` | array | Allowed values |
+| `min` / `max` | number | Range constraints (for `number` type) |
+| `pattern` | string | Regex pattern the value must match |
+| `deprecated` | boolean | Mark as deprecated |
+| `replacement` | string | Suggested replacement for deprecated vars |
+| `description` | string | Human-readable description |
+
+### Security Scanning
+
+EnvGuard detects these secret types:
+
+- AWS Access Keys & Secret Keys
+- GitHub / GitLab Tokens
+- Slack Tokens
+- Stripe Live Keys
+- Private Keys (RSA, EC, DSA)
+- JWT Secrets
+- Database URLs with embedded passwords
+- Generic API Keys, Passwords, and Secrets
+
+### CI/CD Integration
+
+**GitHub Actions:**
+
+```yaml
+- name: Validate env config
+  run: npx envguard validate
+
+- name: Security check
+  run: npx envguard check
+```
+
+The command exits with code `1` on validation errors or critical security findings, failing the build.
+
+### Programmatic API
+
+```js
+const { validateEnv, scanForSecrets, generateEnvExample } = require('envguard');
+
+const schema = { PORT: { required: true, type: 'port' } };
+const result = validateEnv(process.env, schema);
+// { valid: true, errors: [], warnings: [], checked: 1 }
+
+const secrets = scanForSecrets(process.env);
+// { findings: [], hasCritical: false, total: 0 }
+
+const example = generateEnvExample(schema);
+// "# Server port\n# type: port\nPORT=\n"
+```
+
+### License
+
+[MIT](LICENSE)
+
+---
+
+<a id="中文"></a>
+
+## 🇨🇳 中文
+
+### 为什么需要 EnvGuard？
+
+环境变量配置错误是生产事故的主要原因之一。EnvGuard 提供**一站式工具**来验证、保护和文档化项目配置——在错误到达生产环境之前就将其捕获。
+
+### 功能特性
+
+- **Schema 验证** — 为每个变量定义类型、必填、枚举、范围和正则模式
+- **安全扫描** — 检测意外提交的密钥（AWS 密钥、GitHub Token、私钥等）
+- **自动文档** — 从 Schema 生成 `.env.example` 和 Markdown 文档
+- **环境对比** — 比较 dev/staging/prod 的 `.env` 文件差异
+- **CI/CD 就绪** — 退出码和 GitHub Action 集成，支持自动化检查
+- **零依赖** — 纯 Node.js 实现，无需外部包
+- **多格式支持** — 支持 `.env`、`.env.local`、`.env.production` 等
+
+### 快速开始
+
+```bash
+# 安装
+npm install -g envguard
+
+# 创建配置
+envguard init
+
+# 验证环境变量
+envguard validate
+
+# 扫描敏感信息
+envguard check
+
+# 生成文档
+envguard docs
+
+# 对比环境差异
+envguard diff .env.development .env.production
+```
+
+### 配置
+
+在项目根目录创建 `envguard.config.js`：
+
+```js
+module.exports = {
+  schema: {
+    NODE_ENV: {
+      required: true,
+      type: 'string',
+      enum: ['development', 'staging', 'production', 'test'],
+      description: '应用运行环境',
+    },
+    PORT: {
+      required: false,
+      type: 'port',
+      default: '3000',
+      description: '服务端口',
+    },
+    DATABASE_URL: {
+      required: true,
+      type: 'url',
+      description: '数据库连接字符串',
+    },
+    JWT_SECRET: {
+      required: true,
+      type: 'string',
+      description: 'JWT 签名密钥',
+    },
+  },
+  security: {
+    minSeverity: 'medium',
+    ignoreKeys: [],
+  },
+};
+```
+
+### 支持的类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `string` | 任意字符串 | `任意文本` |
+| `number` | 数值，支持 min/max | `42` |
+| `boolean` | true/false、1/0、yes/no | `true` |
+| `url` | 合法 URL | `https://example.com` |
+| `email` | 合法邮箱 | `user@example.com` |
+| `port` | 合法端口号 (0-65535) | `3000` |
+| `json` | 合法 JSON 字符串 | `'{"key":"value"}'` |
+| `regex` | 合法正则表达式 | `^\\d+$` |
+
+### 安全扫描
+
+EnvGuard 可检测以下密钥类型：
+
+- AWS 访问密钥和密钥
+- GitHub / GitLab Token
+- Slack Token
+- Stripe Live Key
+- 私钥（RSA、EC、DSA）
+- JWT 密钥
+- 包含密码的数据库连接 URL
+- 通用 API Key、密码和密钥
+
+### CI/CD 集成
+
+**GitHub Actions：**
+
+```yaml
+- name: 验证环境配置
+  run: npx envguard validate
+
+- name: 安全检查
+  run: npx envguard check
+```
+
+验证失败或发现严重安全问题时，命令以退出码 `1` 退出，使构建失败。
+
+### 编程式 API
+
+```js
+const { validateEnv, scanForSecrets, generateEnvExample } = require('envguard');
+
+const schema = { PORT: { required: true, type: 'port' } };
+const result = validateEnv(process.env, schema);
+// { valid: true, errors: [], warnings: [], checked: 1 }
+
+const secrets = scanForSecrets(process.env);
+// { findings: [], hasCritical: false, total: 0 }
+
+const example = generateEnvExample(schema);
+// "# Server port\n# type: port\nPORT=\n"
+```
+
+### 许可证
+
+[MIT](LICENSE)
+
+---
+
+<a id="日本語"></a>
+
+## 🇯🇵 日本語
+
+### なぜ EnvGuard が必要か？
+
+環境変数の設定ミスは本番障害の主要な原因の一つです。EnvGuard は、プロジェクトの設定を検証・保護・文書化する**オールインワンツール**を提供し、エラーが本番環境に到達する前に検出します。
+
+### 機能
+
+- **スキーマ検証** — 各変数の型、必須、列挙、範囲、正規表現パターンを定義
+- **セキュリティスキャン** — 誤ってコミットされたシークレットの検出（AWS キー、GitHub トークン、秘密鍵など）
+- **自動ドキュメント生成** — スキーマから `.env.example` と Markdown ドキュメントを生成
+- **環境比較** — dev/staging/prod の `.env` ファイルの差分を検出
+- **CI/CD 対応** — 終了コードと GitHub Action 統合による自動チェック
+- **ゼロ依存** — 外部パッケージ不要のピュア Node.js 実装
+- **マルチフォーマット対応** — `.env`、`.env.local`、`.env.production` などに対応
+
+### クイックスタート
+
+```bash
+# インストール
+npm install -g envguard
+
+# 設定ファイルの作成
+envguard init
+
+# 環境変数の検証
+envguard validate
+
+# セキュリティスキャン
+envguard check
+
+# ドキュメント生成
+envguard docs
+
+# 環境の比較
+envguard diff .env.development .env.production
+```
+
+### 設定
+
+プロジェクトルートに `envguard.config.js` を作成：
+
+```js
+module.exports = {
+  schema: {
+    NODE_ENV: {
+      required: true,
+      type: 'string',
+      enum: ['development', 'staging', 'production', 'test'],
+      description: 'アプリケーション環境',
+    },
+    PORT: {
+      required: false,
+      type: 'port',
+      default: '3000',
+      description: 'サーバーポート',
+    },
+    DATABASE_URL: {
+      required: true,
+      type: 'url',
+      description: 'データベース接続文字列',
+    },
+    JWT_SECRET: {
+      required: true,
+      type: 'string',
+      description: 'JWT 署名用シークレットキー',
+    },
+  },
+  security: {
+    minSeverity: 'medium',
+    ignoreKeys: [],
+  },
+};
+```
+
+### サポート型
+
+| 型 | 説明 | 例 |
+|----|------|-----|
+| `string` | 任意の文字列 | `任意のテキスト` |
+| `number` | 数値（min/max 対応） | `42` |
+| `boolean` | true/false、1/0、yes/no | `true` |
+| `url` | 有効な URL | `https://example.com` |
+| `email` | 有効なメールアドレス | `user@example.com` |
+| `port` | 有効なポート番号 (0-65535) | `3000` |
+| `json` | 有効な JSON 文字列 | `'{"key":"value"}'` |
+| `regex` | 有効な正規表現パターン | `^\\d+$` |
+
+### セキュリティスキャン
+
+EnvGuard は以下のシークレットタイプを検出します：
+
+- AWS アクセスキー・シークレットキー
+- GitHub / GitLab トークン
+- Slack トークン
+- Stripe ライブキー
+- 秘密鍵（RSA、EC、DSA）
+- JWT シークレット
+- パスワード埋め込みデータベース URL
+- 汎用 API キー、パスワード、シークレット
+
+### CI/CD 統合
+
+**GitHub Actions：**
+
+```yaml
+- name: 環境設定の検証
+  run: npx envguard validate
+
+- name: セキュリティチェック
+  run: npx envguard check
+```
+
+検証エラーや重大なセキュリティ問題が見つかった場合、コマンドは終了コード `1` で終了し、ビルドを失敗させます。
+
+### プログラマティック API
+
+```js
+const { validateEnv, scanForSecrets, generateEnvExample } = require('envguard');
+
+const schema = { PORT: { required: true, type: 'port' } };
+const result = validateEnv(process.env, schema);
+// { valid: true, errors: [], warnings: [], checked: 1 }
+
+const secrets = scanForSecrets(process.env);
+// { findings: [], hasCritical: false, total: 0 }
+
+const example = generateEnvExample(schema);
+// "# Server port\n# type: port\nPORT=\n"
+```
+
+### ライセンス
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@anhuijie/envguard",
+  "version": "1.0.0",
+  "description": "Environment variable & config validation, security scanning, and documentation generator for modern projects",
+  "main": "src/index.js",
+  "bin": {
+    "envguard": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "env",
+    "environment-variables",
+    "config",
+    "validation",
+    "security",
+    "dotenv",
+    "schema",
+    "documentation",
+    "ci-cd"
+  ],
+  "author": "AnhuiJie <anhuijie@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AnhuiJie/envguard"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * EnvGuard CLI — Environment variable & config validation, security scanning, and documentation generator
+ */
+
+const { runInit } = require('./commands/init');
+const { runValidate } = require('./commands/validate');
+const { runCheck } = require('./commands/check');
+const { runDocs } = require('./commands/docs');
+const { runDiff } = require('./commands/diff');
+
+const VERSION = '1.0.0';
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  const options = {};
+  const positional = [];
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        options[key] = next;
+        i++;
+      } else {
+        options[key] = true;
+      }
+    } else {
+      positional.push(args[i]);
+    }
+  }
+
+  // Map positional args to command-specific options
+  if (command === 'diff' && positional.length >= 2) {
+    options.fileA = positional[0];
+    options.fileB = positional[1];
+  }
+
+  return { command, options };
+}
+
+function printHelp() {
+  console.log(`
+EnvGuard v${VERSION} — Environment variable & config validation, security scanning, and documentation generator
+
+Usage:
+  envguard <command> [options]
+
+Commands:
+  init              Create envguard.config.js template
+  validate          Validate environment variables against schema
+  check             Scan .env files for sensitive information
+  docs              Generate .env.example and documentation
+  diff              Compare two .env files
+
+Options:
+  --config <path>   Path to config file
+  --env-file <path> Path to .env file
+  --output <dir>    Output directory for docs
+  --severity <level> Minimum severity for security check (low|medium|high|critical)
+  --recursive       Scan subdirectories for .env files
+  --force           Overwrite existing files
+  --allow-failure   Exit with code 0 even on errors
+  --help            Show this help message
+  --version         Show version number
+
+Examples:
+  envguard init
+  envguard validate
+  envguard validate --env-file .env.production
+  envguard check --recursive
+  envguard docs --output ./docs
+  envguard diff .env.development .env.production
+`);
+}
+
+function main() {
+  const { command, options } = parseArgs(process.argv);
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.version) {
+    console.log(`EnvGuard v${VERSION}`);
+    return;
+  }
+
+  switch (command) {
+    case 'init':
+      runInit({ ...options, cwd: process.cwd() });
+      break;
+    case 'validate':
+      runValidate({ ...options, cwd: process.cwd() });
+      break;
+    case 'check':
+      runCheck({ ...options, cwd: process.cwd() });
+      break;
+    case 'docs':
+      runDocs({ ...options, cwd: process.cwd() });
+      break;
+    case 'diff':
+      runDiff({ ...options, cwd: process.cwd() });
+      break;
+    default:
+      printHelp();
+      if (command) {
+        console.log(`Unknown command: ${command}`);
+      }
+      break;
+  }
+}
+
+main();

package/src/commands/check.js

@@ -0,0 +1,63 @@
+/**
+ * envguard check — scan for sensitive information in .env files
+ */
+
+const { scanForSecrets } = require('../core/security');
+const { formatFinding, printHeader, colorize } = require('../utils/format');
+const { findEnvFiles, loadEnvFile } = require('../utils/file');
+
+function runCheck(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  printHeader('EnvGuard — Security Check');
+
+  // Find .env files
+  const envFiles = findEnvFiles(cwd, { recursive: options.recursive });
+
+  if (envFiles.length === 0) {
+    console.log(colorize('No .env files found.', 'yellow'));
+    return { findings: [], total: 0 };
+  }
+
+  console.log(`Scanning ${envFiles.length} file(s)...\n`);
+
+  let allFindings = [];
+
+  for (const filePath of envFiles) {
+    const envObj = loadEnvFile(filePath);
+    const result = scanForSecrets(envObj, {
+      ignoreKeys: options.ignoreKeys,
+      minSeverity: options.severity || 'medium',
+    });
+
+    if (result.findings.length > 0) {
+      console.log(colorize(`📄 ${filePath}`, 'bold'));
+      for (const finding of result.findings) {
+        console.log(`  ${formatFinding(finding)}`);
+      }
+      console.log('');
+      allFindings = allFindings.concat(
+        result.findings.map((f) => ({ ...f, file: filePath }))
+      );
+    }
+  }
+
+  if (allFindings.length === 0) {
+    console.log(colorize('✓ No sensitive information detected!', 'green'));
+  } else {
+    console.log(colorize(`Found ${allFindings.length} potential issue(s)`, 'yellow'));
+    if (allFindings.some((f) => f.severity === 'critical')) {
+      console.log(colorize('  Critical issues found! Do not commit these files.', 'red'));
+    }
+  }
+
+  console.log('');
+
+  if (allFindings.some((f) => f.severity === 'critical') && !options.allowFailure) {
+    process.exit(1);
+  }
+
+  return { findings: allFindings, total: allFindings.length };
+}
+
+module.exports = { runCheck };