@anhuijie/envguard 1.0.0

package/src/commands/diff.js

@@ -0,0 +1,59 @@
+/**
+ * envguard diff — compare environment files across environments
+ */
+
+const { diffEnvs, formatDiffResult } = require('../core/diff');
+const { printHeader, colorize } = require('../utils/format');
+const fs = require('fs');
+const path = require('path');
+
+function runDiff(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  printHeader('EnvGuard — Environment Diff');
+
+  const fileA = options.fileA;
+  const fileB = options.fileB;
+
+  if (!fileA || !fileB) {
+    console.error('Usage: envguard diff <fileA> <fileB>');
+    console.error('Example: envguard diff .env.development .env.production');
+    process.exit(1);
+  }
+
+  const pathA = path.resolve(cwd, fileA);
+  const pathB = path.resolve(cwd, fileB);
+
+  if (!fs.existsSync(pathA)) {
+    console.error(`File not found: ${fileA}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(pathB)) {
+    console.error(`File not found: ${fileB}`);
+    process.exit(1);
+  }
+
+  // Parse both files
+  const { parseEnvFile } = require('../core/diff');
+  const envA = parseEnvFile(pathA);
+  const envB = parseEnvFile(pathB);
+
+  // Diff
+  const labelA = path.basename(fileA);
+  const labelB = path.basename(fileB);
+  const result = diffEnvs(envA, envB, labelA, labelB);
+
+  // Output
+  console.log(formatDiffResult(result, labelA, labelB));
+  console.log('');
+
+  if (result.summary.onlyInA > 0 || result.summary.onlyInB > 0 || result.summary.valueDiff > 0) {
+    console.log(colorize('⚠ Environments are not in sync', 'yellow'));
+  } else {
+    console.log(colorize('✓ Environments are in sync', 'green'));
+  }
+
+  return result;
+}
+
+module.exports = { runDiff };

package/src/commands/docs.js

@@ -0,0 +1,45 @@
+/**
+ * envguard docs — generate .env.example and documentation
+ */
+
+const { parseSchema } = require('../core/schema');
+const { writeDocs } = require('../core/docs');
+const { findConfigFile } = require('../utils/file');
+const { printHeader, colorize } = require('../utils/format');
+const path = require('path');
+
+function runDocs(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  printHeader('EnvGuard — Generate Docs');
+
+  // Find config
+  const configPath = options.config || findConfigFile(cwd);
+  if (!configPath) {
+    console.error('No envguard.config.js found. Run "envguard init" to create one.');
+    process.exit(1);
+  }
+
+  // Parse schema
+  let config;
+  try {
+    config = parseSchema(configPath);
+  } catch (err) {
+    console.error(`Config error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Generate docs
+  const outputDir = options.output || cwd;
+  const projectName = options.projectName || path.basename(cwd);
+
+  const result = writeDocs(config.schema, outputDir, { projectName });
+
+  console.log(colorize(`✓ Generated: ${path.relative(cwd, result.examplePath)}`, 'green'));
+  console.log(colorize(`✓ Generated: ${path.relative(cwd, result.mdPath)}`, 'green'));
+  console.log('');
+
+  return result;
+}
+
+module.exports = { runDocs };

package/src/commands/init.js

@@ -0,0 +1,101 @@
+/**
+ * envguard init — create envguard.config.js template
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { printHeader, colorize } = require('../utils/format');
+const { loadEnvFile } = require('../utils/file');
+
+const CONFIG_TEMPLATE = `/**
+ * EnvGuard Configuration
+ * @see https://github.com/AnhuiJie/envguard#configuration
+ */
+module.exports = {
+  // Define your environment variable schema
+  schema: {
+    // ── Application ──────────────────────
+    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 ─────────────────────────
+    DATABASE_URL: {
+      required: true,
+      type: 'url',
+      description: 'Database connection string',
+    },
+
+    // ── Authentication ───────────────────
+    JWT_SECRET: {
+      required: true,
+      type: 'string',
+      description: 'Secret key for JWT signing',
+    },
+
+    // ── External Services ────────────────
+    // API_KEY: {
+    //   required: false,
+    //   type: 'string',
+    //   description: 'External API key',
+    // },
+  },
+
+  // Security scanning options
+  security: {
+    // Minimum severity to report: 'low' | 'medium' | 'high' | 'critical'
+    minSeverity: 'medium',
+    // Keys to ignore during security scan
+    ignoreKeys: [],
+  },
+
+  // Documentation generation options
+  docs: {
+    projectName: '{{PROJECT_NAME}}',
+  },
+};
+`;
+
+function runInit(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  printHeader('EnvGuard — Init');
+
+  const configPath = path.join(cwd, 'envguard.config.js');
+
+  if (fs.existsSync(configPath) && !options.force) {
+    console.log(colorize('envguard.config.js already exists. Use --force to overwrite.', 'yellow'));
+    return;
+  }
+
+  // Try to auto-detect variables from existing .env
+  const envObj = loadEnvFile(path.join(cwd, '.env'));
+  let content = CONFIG_TEMPLATE;
+
+  if (Object.keys(envObj).length > 0) {
+    console.log(colorize(`Detected ${Object.keys(envObj).length} variable(s) in .env`, 'cyan'));
+    console.log('Review and update the generated config as needed.\n');
+  }
+
+  content = content.replace('{{PROJECT_NAME}}', path.basename(cwd));
+
+  fs.writeFileSync(configPath, content, 'utf-8');
+  console.log(colorize(`✓ Created envguard.config.js`, 'green'));
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Edit envguard.config.js to define your schema');
+  console.log('  2. Run: npx envguard validate');
+  console.log('  3. Run: npx envguard check');
+  console.log('  4. Run: npx envguard docs');
+}
+
+module.exports = { runInit };

package/src/commands/validate.js

@@ -0,0 +1,72 @@
+/**
+ * envguard validate — validate environment variables against schema
+ */
+
+const { validateEnv } = require('../core/validator');
+const { parseSchema } = require('../core/schema');
+const { formatError, formatWarning, formatSuccess, printHeader, printSummary } = require('../utils/format');
+const { findConfigFile, loadEnvFile } = require('../utils/file');
+const path = require('path');
+
+function runValidate(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  printHeader('EnvGuard — Validate');
+
+  // Find config
+  const configPath = options.config || findConfigFile(cwd);
+  if (!configPath) {
+    console.error('No envguard.config.js found. Run "envguard init" to create one.');
+    process.exit(1);
+  }
+
+  console.log(`Using config: ${path.relative(cwd, configPath)}`);
+
+  // Parse schema
+  let config;
+  try {
+    config = parseSchema(configPath);
+  } catch (err) {
+    console.error(`Config error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Load env values
+  let envObj;
+  if (options.envFile) {
+    envObj = loadEnvFile(path.resolve(cwd, options.envFile));
+  } else {
+    // Merge process.env with .env file
+    envObj = { ...loadEnvFile(path.join(cwd, '.env')), ...process.env };
+  }
+
+  // Validate
+  const results = validateEnv(envObj, config.schema);
+
+  // Print results
+  for (const error of results.errors) {
+    console.log(formatError(error));
+  }
+  for (const warning of results.warnings) {
+    console.log(formatWarning(warning));
+  }
+
+  // Print checked variables that passed
+  const errorKeys = new Set(results.errors.map((e) => e.key));
+  const warningKeys = new Set(results.warnings.map((w) => w.key));
+  for (const key of Object.keys(config.schema)) {
+    if (!errorKeys.has(key) && !warningKeys.has(key)) {
+      console.log(formatSuccess(key));
+    }
+  }
+
+  printSummary(results);
+
+  if (!results.valid && !options.allowFailure) {
+    process.exit(1);
+  }
+
+  return results;
+}
+
+module.exports = { runValidate };

package/src/core/diff.js

@@ -0,0 +1,111 @@
+/**
+ * Multi-environment config diff tool
+ * Compares .env files across environments (dev/staging/prod)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function parseEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const vars = {};
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip comments and empty lines
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    let value = trimmed.slice(eqIndex + 1).trim();
+
+    // Remove surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    vars[key] = value;
+  }
+
+  return vars;
+}
+
+function diffEnvs(envA, envB, labelA = 'A', labelB = 'B') {
+  const keysA = new Set(Object.keys(envA));
+  const keysB = new Set(Object.keys(envB));
+
+  const onlyInA = [...keysA].filter((k) => !keysB.has(k));
+  const onlyInB = [...keysB].filter((k) => !keysA.has(k));
+  const common = [...keysA].filter((k) => keysB.has(k));
+
+  const valueDiff = common
+    .filter((k) => envA[k] !== envB[k])
+    .map((k) => ({
+      key: k,
+      [labelA]: envA[k],
+      [labelB]: envB[k],
+    }));
+
+  return {
+    onlyInA: onlyInA.map((k) => ({ key: k, value: envA[k] })),
+    onlyInB: onlyInB.map((k) => ({ key: k, value: envB[k] })),
+    valueDiff,
+    identical: common.filter((k) => envA[k] === envB[k]),
+    summary: {
+      totalA: keysA.size,
+      totalB: keysB.size,
+      onlyInA: onlyInA.length,
+      onlyInB: onlyInB.length,
+      valueDiff: valueDiff.length,
+      identical: common.filter((k) => envA[k] === envB[k]).length,
+    },
+  };
+}
+
+function formatDiffResult(result, labelA, labelB) {
+  const lines = [];
+
+  lines.push(`Environment Diff: ${labelA} ↔ ${labelB}`);
+  lines.push('═'.repeat(50));
+  lines.push('');
+
+  lines.push(`Summary: ${result.summary.totalA} vars in ${labelA}, ${result.summary.totalB} vars in ${labelB}`);
+  lines.push(`  ${result.summary.identical} identical, ${result.summary.valueDiff} different`);
+  lines.push('');
+
+  if (result.onlyInA.length > 0) {
+    lines.push(`Only in ${labelA}:`);
+    for (const item of result.onlyInA) {
+      lines.push(`  - ${item.key}=${item.value}`);
+    }
+    lines.push('');
+  }
+
+  if (result.onlyInB.length > 0) {
+    lines.push(`Only in ${labelB}:`);
+    for (const item of result.onlyInB) {
+      lines.push(`  - ${item.key}=${item.value}`);
+    }
+    lines.push('');
+  }
+
+  if (result.valueDiff.length > 0) {
+    lines.push('Different values:');
+    for (const item of result.valueDiff) {
+      lines.push(`  - ${item.key}:`);
+      lines.push(`      ${labelA}: ${item[labelA]}`);
+      lines.push(`      ${labelB}: ${item[labelB]}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { parseEnvFile, diffEnvs, formatDiffResult };

package/src/core/docs.js

@@ -0,0 +1,120 @@
+/**
+ * Documentation generator - creates .env.example and markdown docs from schema
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function generateEnvExample(schema, options = {}) {
+  const lines = [
+    '# Environment Variables',
+    '# Generated by EnvGuard — do not edit manually',
+    '# Run: npx envguard docs to regenerate',
+    '',
+  ];
+
+  // Group by optional tags
+  const required = [];
+  const optional = [];
+
+  for (const [key, rule] of Object.entries(schema)) {
+    if (rule.required) {
+      required.push([key, rule]);
+    } else {
+      optional.push([key, rule]);
+    }
+  }
+
+  if (required.length > 0) {
+    lines.push('# ── Required ──────────────────────────');
+    for (const [key, rule] of required) {
+      lines.push(...formatVarLine(key, rule));
+    }
+    lines.push('');
+  }
+
+  if (optional.length > 0) {
+    lines.push('# ── Optional ──────────────────────────');
+    for (const [key, rule] of optional) {
+      lines.push(...formatVarLine(key, rule));
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatVarLine(key, rule) {
+  const lines = [];
+  const desc = rule.description || rule.desc || '';
+  const type = rule.type || 'string';
+
+  if (desc) {
+    lines.push(`# ${desc}`);
+  }
+
+  let typeInfo = `type: ${type}`;
+  if (rule.enum) typeInfo += `, allowed: ${rule.enum.join(' | ')}`;
+  if (rule.min !== undefined) typeInfo += `, min: ${rule.min}`;
+  if (rule.max !== undefined) typeInfo += `, max: ${rule.max}`;
+  lines.push(`# ${typeInfo}`);
+
+  if (rule.deprecated) {
+    lines.push(`# ⚠ DEPRECATED${rule.replacement ? ` — use ${rule.replacement} instead` : ''}`);
+  }
+
+  const defaultVal = rule.default !== undefined ? rule.default : '';
+  lines.push(`${key}=${defaultVal}`);
+  lines.push('');
+
+  return lines;
+}
+
+function generateMarkdownDoc(schema, options = {}) {
+  const projectName = options.projectName || 'Project';
+  const lines = [
+    `# ${projectName} — Environment Variables`,
+    '',
+    '> Auto-generated by [EnvGuard](https://github.com/AnhuiJie/envguard)',
+    '',
+    '| Variable | Required | Type | Default | Description |',
+    '|----------|----------|------|---------|-------------|',
+  ];
+
+  for (const [key, rule] of Object.entries(schema)) {
+    const required = rule.required ? 'Yes' : 'No';
+    const type = rule.type || 'string';
+    const defaultVal = rule.default !== undefined ? `\`${rule.default}\`` : '—';
+    let desc = rule.description || rule.desc || '';
+
+    if (rule.enum) desc += ` (allowed: ${rule.enum.map((v) => `\`${v}\``).join(', ')})`;
+    if (rule.deprecated) desc += ` ⚠ **Deprecated**${rule.replacement ? `, use \`${rule.replacement}\`` : ''}`;
+    if (rule.min !== undefined) desc += ` (min: ${rule.min})`;
+    if (rule.max !== undefined) desc += ` (max: ${rule.max})`;
+
+    lines.push(`| \`${key}\` | ${required} | ${type} | ${defaultVal} | ${desc} |`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+function writeDocs(schema, outputDir, options = {}) {
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write .env.example
+  const exampleContent = generateEnvExample(schema, options);
+  const examplePath = path.join(outputDir, '.env.example');
+  fs.writeFileSync(examplePath, exampleContent, 'utf-8');
+
+  // Write markdown doc
+  const mdContent = generateMarkdownDoc(schema, options);
+  const mdPath = path.join(outputDir, 'ENV.md');
+  fs.writeFileSync(mdPath, mdContent, 'utf-8');
+
+  return { examplePath, mdPath };
+}
+
+module.exports = { generateEnvExample, generateMarkdownDoc, writeDocs };

package/src/core/index.js

@@ -0,0 +1,22 @@
+/**
+ * EnvGuard core module — unified API
+ */
+
+const { parseSchema, validateSchema } = require('./schema');
+const { validateEnv } = require('./validator');
+const { scanForSecrets } = require('./security');
+const { generateEnvExample, generateMarkdownDoc, writeDocs } = require('./docs');
+const { parseEnvFile, diffEnvs, formatDiffResult } = require('./diff');
+
+module.exports = {
+  parseSchema,
+  validateSchema,
+  validateEnv,
+  scanForSecrets,
+  generateEnvExample,
+  generateMarkdownDoc,
+  writeDocs,
+  parseEnvFile,
+  diffEnvs,
+  formatDiffResult,
+};

package/src/core/schema.js

@@ -0,0 +1,74 @@
+/**
+ * Schema definition and parsing for envguard.config.js
+ */
+
+const SUPPORTED_TYPES = ['string', 'number', 'boolean', 'url', 'email', 'json', 'regex', 'port'];
+
+function validateSchema(schema) {
+  if (!schema || typeof schema !== 'object') {
+    throw new Error('Schema must be a non-empty object');
+  }
+
+  const errors = [];
+
+  for (const [key, rule] of Object.entries(schema)) {
+    if (!rule || typeof rule !== 'object') {
+      errors.push(`Variable "${key}": rule must be an object`);
+      continue;
+    }
+
+    if (rule.type && !SUPPORTED_TYPES.includes(rule.type)) {
+      errors.push(`Variable "${key}": unsupported type "${rule.type}". Supported: ${SUPPORTED_TYPES.join(', ')}`);
+    }
+
+    if (rule.type === 'number' && rule.min !== undefined && rule.max !== undefined && rule.min > rule.max) {
+      errors.push(`Variable "${key}": min (${rule.min}) cannot be greater than max (${rule.max})`);
+    }
+
+    if (rule.enum && !Array.isArray(rule.enum)) {
+      errors.push(`Variable "${key}": enum must be an array`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Schema validation failed:\n  ${errors.join('\n  ')}`);
+  }
+
+  return true;
+}
+
+function parseSchema(configPath) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`Config file not found: ${configPath}`);
+    }
+
+    // Clear require cache for fresh reload
+    delete require.cache[require.resolve(path.resolve(configPath))];
+
+    const config = require(path.resolve(configPath));
+
+    if (!config.schema && !config.env) {
+      throw new Error('Config must export a "schema" or "env" object');
+    }
+
+    const schema = config.schema || config.env;
+    validateSchema(schema);
+
+    return {
+      schema,
+      security: config.security || {},
+      docs: config.docs || {},
+    };
+  } catch (err) {
+    if (err.code === 'MODULE_NOT_FOUND') {
+      throw new Error(`Cannot load config: ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+module.exports = { validateSchema, parseSchema, SUPPORTED_TYPES };