@claude-agent/envcheck 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claude Agent
+
+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,227 @@
+# envcheck
+
+[![npm version](https://img.shields.io/npm/v/@claude-agent/envcheck.svg)](https://www.npmjs.com/package/@claude-agent/envcheck)
+[![npm downloads](https://img.shields.io/npm/dm/@claude-agent/envcheck.svg)](https://www.npmjs.com/package/@claude-agent/envcheck)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Validate .env files, compare with .env.example, find missing or empty variables.
+
+Never deploy with missing environment variables again.
+
+**Built autonomously by [Claude](https://claude.ai)** - an AI assistant by Anthropic.
+
+## Installation
+
+```bash
+npm install -g @claude-agent/envcheck
+```
+
+Or use directly with npx:
+
+```bash
+npx @claude-agent/envcheck
+```
+
+## Quick Start
+
+```bash
+# Check .env against .env.example (auto-detected)
+envcheck
+
+# Check specific file
+envcheck .env.production
+
+# Require specific variables
+envcheck -r "DATABASE_URL,API_KEY"
+
+# Compare two files
+envcheck compare .env .env.staging
+
+# List variables
+envcheck list .env
+
+# Get specific value
+envcheck get .env API_KEY
+```
+
+## CLI Usage
+
+### Check Command (Default)
+
+```bash
+# Auto-detect .env.example in same directory
+envcheck
+
+# Specify example file
+envcheck -e .env.example.prod .env.production
+
+# Require specific variables
+envcheck -r "DB_HOST,DB_USER,DB_PASS"
+
+# Warn on empty values
+envcheck --no-empty
+
+# Error on extra variables not in example
+envcheck --no-extra
+
+# Treat warnings as errors
+envcheck --strict
+
+# JSON output
+envcheck -j
+
+# Quiet mode (only errors)
+envcheck -q
+```
+
+### Compare Command
+
+```bash
+# Compare two env files
+envcheck compare .env .env.example
+
+# JSON output
+envcheck compare .env .env.prod -j
+```
+
+### List Command
+
+```bash
+# List all variable names
+envcheck list .env
+
+# JSON output
+envcheck list .env -j
+```
+
+### Get Command
+
+```bash
+# Get a specific variable value
+envcheck get .env DATABASE_URL
+```
+
+## API Usage
+
+```javascript
+const { check, compare, validate, parse, list, get, generate } = require('@claude-agent/envcheck');
+
+// Full check against example
+const result = check('.env', {
+  examplePath: '.env.example',
+  required: ['DATABASE_URL'],
+  noEmpty: true,
+  strict: false
+});
+
+console.log(result.valid);      // true/false
+console.log(result.issues);     // Array of issues
+console.log(result.summary);    // { errors: 0, warnings: 0 }
+
+// Compare two files
+const diff = compare('.env', '.env.example');
+console.log(diff.missing);      // Variables in example but not in env
+console.log(diff.extra);        // Variables in env but not in example
+console.log(diff.empty);        // Variables that are empty in env
+
+// Validate a single file
+const validation = validate('.env', {
+  required: ['API_KEY', 'SECRET'],
+  noEmpty: true
+});
+
+// Parse env content directly
+const parsed = parse('FOO=bar\nBAZ=qux');
+console.log(parsed.variables);  // { FOO: 'bar', BAZ: 'qux' }
+
+// List variables
+const vars = list('.env');      // ['FOO', 'BAZ', ...]
+
+// Get specific variable
+const value = get('.env', 'API_KEY');
+
+// Generate .env from example with defaults
+const content = generate('.env.example', {
+  DATABASE_URL: 'postgres://localhost/mydb',
+  API_KEY: 'dev-key'
+});
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed |
+| 1 | Errors found (missing vars, invalid syntax, etc.) |
+
+## Example Output
+
+```
+$ envcheck
+Checking .env against .env.example...
+
+✗ Missing variable 'DATABASE_URL' (defined in example at line 3)
+✗ Missing variable 'REDIS_URL' (defined in example at line 5)
+! Variable 'API_KEY' is empty (line 7)
+
+2 error(s), 1 warning(s)
+```
+
+```
+$ envcheck compare .env .env.prod
+Comparing .env with .env.prod...
+
+.env: 12 variables
+.env.prod: 15 variables
+
+Missing (in example but not in env):
+  - NEW_RELIC_KEY
+  - SENTRY_DSN
+  - CDN_URL
+
+Extra (in env but not in example):
+  - DEBUG
+```
+
+## Use Cases
+
+- **CI/CD Pipelines**: Validate env before deployment
+- **Onboarding**: Check if developer has all required env vars
+- **Documentation**: List required variables from example file
+- **Debugging**: Compare env files across environments
+
+## .env File Format
+
+Supports standard .env syntax:
+
+```bash
+# Comments
+KEY=value
+QUOTED="value with spaces"
+MULTILINE="line1\nline2"
+EMPTY=
+WITH_EQUALS=postgres://user:pass@host/db?opt=val
+```
+
+## Why This Tool?
+
+- **Zero dependencies** - Fast install, no bloat
+- **Auto-detection** - Finds .env.example automatically
+- **CI-friendly** - Exit codes and JSON output
+- **Comprehensive** - Parse, validate, compare, generate
+- **Well-tested** - 46 tests covering edge cases
+
+## Related Tools
+
+- [@claude-agent/changelog-gen](https://www.npmjs.com/package/@claude-agent/changelog-gen) - Generate changelogs from commits
+- [@claude-agent/gitstat](https://www.npmjs.com/package/@claude-agent/gitstat) - Git repository statistics
+- [@claude-agent/portfinder](https://www.npmjs.com/package/@claude-agent/portfinder) - Find/kill processes by port
+- [@claude-agent/cron-explain](https://www.npmjs.com/package/@claude-agent/cron-explain) - Explain cron expressions
+
+## License
+
+MIT
+
+---
+
+*Part of the [claude-agent-tools](https://github.com/claude-agent-tools) collection.*

package/bin/cli.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+'use strict';
+
+const { check, compare, validate, list, get, readEnvFile } = require('../src/index.js');
+const path = require('path');
+const fs = require('fs');
+
+const VERSION = '1.0.0';
+
+const HELP = `
+envcheck - Validate .env files
+
+USAGE
+  envcheck [options] [file]
+  envcheck compare <env> <example>
+
+COMMANDS
+  check (default)    Check .env file, optionally against .env.example
+  compare            Compare two env files
+  list               List variables in a file
+  get <key>          Get a specific variable value
+
+OPTIONS
+  -e, --example <file>   Compare with example file (default: .env.example)
+  -r, --required <vars>  Comma-separated required variables
+  --no-empty             Warn on empty values
+  --no-extra             Error on variables not in example
+  --strict               Treat warnings as errors
+  -q, --quiet            Only output errors
+  -j, --json             Output as JSON
+  -v, --version          Show version
+  -h, --help             Show this help
+
+EXAMPLES
+  envcheck                          Check .env against .env.example
+  envcheck .env.production          Check specific file
+  envcheck -r "API_KEY,DB_URL"      Require specific variables
+  envcheck compare .env .env.prod   Compare two files
+  envcheck list .env                List all variables
+  envcheck get .env API_KEY         Get specific value
+`;
+
+function parseArgs(args) {
+  const result = {
+    command: 'check',
+    file: '.env',
+    example: null,
+    required: [],
+    noEmpty: false,
+    noExtra: false,
+    strict: false,
+    quiet: false,
+    json: false,
+    args: []
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      console.log(HELP);
+      process.exit(0);
+    }
+
+    if (arg === '-v' || arg === '--version') {
+      console.log(VERSION);
+      process.exit(0);
+    }
+
+    if (arg === '-e' || arg === '--example') {
+      result.example = args[++i];
+    } else if (arg === '-r' || arg === '--required') {
+      result.required = args[++i].split(',').map(s => s.trim());
+    } else if (arg === '--no-empty') {
+      result.noEmpty = true;
+    } else if (arg === '--no-extra') {
+      result.noExtra = true;
+    } else if (arg === '--strict') {
+      result.strict = true;
+    } else if (arg === '-q' || arg === '--quiet') {
+      result.quiet = true;
+    } else if (arg === '-j' || arg === '--json') {
+      result.json = true;
+    } else if (arg === 'compare' || arg === 'list' || arg === 'get') {
+      result.command = arg;
+    } else if (!arg.startsWith('-')) {
+      result.args.push(arg);
+    }
+
+    i++;
+  }
+
+  // Handle positional args based on command
+  if (result.command === 'check' && result.args.length > 0) {
+    result.file = result.args[0];
+  }
+
+  return result;
+}
+
+function formatIssue(issue) {
+  const prefix = issue.type === 'error' ? '\x1b[31m✗\x1b[0m' : '\x1b[33m!\x1b[0m';
+  const line = issue.line ? `:${issue.line}` : '';
+  return `${prefix} ${issue.message}${line ? ` (line ${issue.line})` : ''}`;
+}
+
+function runCheck(opts) {
+  // Auto-detect example file
+  let examplePath = opts.example;
+  if (!examplePath) {
+    const dir = path.dirname(path.resolve(opts.file));
+    const candidates = ['.env.example', '.env.sample', '.env.template', 'env.example'];
+    for (const candidate of candidates) {
+      const p = path.join(dir, candidate);
+      if (fs.existsSync(p)) {
+        examplePath = p;
+        break;
+      }
+    }
+  }
+
+  const result = check(opts.file, {
+    examplePath,
+    required: opts.required,
+    noEmpty: opts.noEmpty,
+    noExtra: opts.noExtra,
+    strict: opts.strict
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.valid ? 0 : 1;
+  }
+
+  if (!opts.quiet) {
+    const fileName = path.basename(opts.file);
+    if (examplePath) {
+      console.log(`Checking ${fileName} against ${path.basename(examplePath)}...\n`);
+    } else {
+      console.log(`Checking ${fileName}...\n`);
+    }
+  }
+
+  if (result.issues.length === 0) {
+    if (!opts.quiet) {
+      console.log('\x1b[32m✓\x1b[0m All checks passed');
+    }
+    return 0;
+  }
+
+  // Group by type
+  const errors = result.issues.filter(i => i.type === 'error');
+  const warnings = result.issues.filter(i => i.type === 'warning');
+
+  for (const issue of errors) {
+    console.log(formatIssue(issue));
+  }
+
+  if (!opts.quiet) {
+    for (const issue of warnings) {
+      console.log(formatIssue(issue));
+    }
+  }
+
+  console.log();
+  if (errors.length > 0) {
+    console.log(`\x1b[31m${errors.length} error(s)\x1b[0m${warnings.length > 0 ? `, ${warnings.length} warning(s)` : ''}`);
+  } else {
+    console.log(`\x1b[33m${warnings.length} warning(s)\x1b[0m`);
+  }
+
+  return result.valid ? 0 : 1;
+}
+
+function runCompare(opts) {
+  if (opts.args.length < 2) {
+    console.error('Usage: envcheck compare <env> <example>');
+    return 1;
+  }
+
+  const [envPath, examplePath] = opts.args;
+  const result = compare(envPath, examplePath);
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  console.log(`Comparing ${path.basename(envPath)} with ${path.basename(examplePath)}...\n`);
+
+  if (!result.env.exists) {
+    console.log(`\x1b[31m✗\x1b[0m File not found: ${envPath}`);
+    return 1;
+  }
+
+  if (!result.example.exists) {
+    console.log(`\x1b[31m✗\x1b[0m File not found: ${examplePath}`);
+    return 1;
+  }
+
+  const envCount = Object.keys(result.env.variables).length;
+  const exampleCount = Object.keys(result.example.variables).length;
+
+  console.log(`${path.basename(envPath)}: ${envCount} variables`);
+  console.log(`${path.basename(examplePath)}: ${exampleCount} variables\n`);
+
+  if (result.missing.length > 0) {
+    console.log('\x1b[31mMissing (in example but not in env):\x1b[0m');
+    for (const item of result.missing) {
+      console.log(`  - ${item.key}`);
+    }
+    console.log();
+  }
+
+  if (result.extra.length > 0) {
+    console.log('\x1b[33mExtra (in env but not in example):\x1b[0m');
+    for (const item of result.extra) {
+      console.log(`  - ${item.key}`);
+    }
+    console.log();
+  }
+
+  if (result.empty.length > 0) {
+    console.log('\x1b[33mEmpty (defined but empty in env):\x1b[0m');
+    for (const item of result.empty) {
+      console.log(`  - ${item.key}`);
+    }
+    console.log();
+  }
+
+  if (result.missing.length === 0 && result.extra.length === 0 && result.empty.length === 0) {
+    console.log('\x1b[32m✓\x1b[0m Files are in sync');
+  }
+
+  return result.missing.length > 0 ? 1 : 0;
+}
+
+function runList(opts) {
+  const file = opts.args[0] || opts.file;
+  const vars = list(file);
+
+  if (opts.json) {
+    console.log(JSON.stringify(vars, null, 2));
+    return 0;
+  }
+
+  if (vars.length === 0) {
+    console.log('No variables found');
+    return 0;
+  }
+
+  for (const v of vars) {
+    console.log(v);
+  }
+
+  return 0;
+}
+
+function runGet(opts) {
+  if (opts.args.length < 2) {
+    console.error('Usage: envcheck get <file> <key>');
+    return 1;
+  }
+
+  const [file, key] = opts.args;
+  const value = get(file, key);
+
+  if (value === undefined) {
+    if (!opts.quiet) {
+      console.error(`Variable '${key}' not found`);
+    }
+    return 1;
+  }
+
+  console.log(value);
+  return 0;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const opts = parseArgs(args);
+
+  let exitCode = 0;
+
+  switch (opts.command) {
+    case 'check':
+      exitCode = runCheck(opts);
+      break;
+    case 'compare':
+      exitCode = runCompare(opts);
+      break;
+    case 'list':
+      exitCode = runList(opts);
+      break;
+    case 'get':
+      exitCode = runGet(opts);
+      break;
+    default:
+      console.error(`Unknown command: ${opts.command}`);
+      exitCode = 1;
+  }
+
+  process.exit(exitCode);
+}
+
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@claude-agent/envcheck",
+  "version": "1.0.0",
+  "description": "Validate .env files, compare with .env.example, find missing or empty variables",
+  "main": "src/index.js",
+  "bin": {
+    "envcheck": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "env",
+    "dotenv",
+    "environment",
+    "variables",
+    "validate",
+    "lint",
+    "cli"
+  ],
+  "author": "Claude Agent <claude-agent@agentmail.to>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/claude-agent-tools/envcheck.git"
+  },
+  "bugs": {
+    "url": "https://github.com/claude-agent-tools/envcheck/issues"
+  },
+  "homepage": "https://github.com/claude-agent-tools/envcheck#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "bin/"
+  ]
+}

package/src/index.js

@@ -0,0 +1,424 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse a .env file into an object
+ * @param {string} content - File content
+ * @returns {Object} Parsed variables
+ */
+function parseEnv(content) {
+  const result = {
+    variables: {},
+    errors: [],
+    warnings: [],
+    lineInfo: {}
+  };
+
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    // Check for valid format
+    const eqIndex = line.indexOf('=');
+    if (eqIndex === -1) {
+      result.errors.push({
+        line: lineNum,
+        message: `Invalid syntax: missing '=' sign`,
+        content: line
+      });
+      continue;
+    }
+
+    const key = line.slice(0, eqIndex).trim();
+    let value = line.slice(eqIndex + 1);
+
+    // Validate key
+    if (!key) {
+      result.errors.push({
+        line: lineNum,
+        message: 'Empty variable name',
+        content: line
+      });
+      continue;
+    }
+
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      result.warnings.push({
+        line: lineNum,
+        message: `Variable name '${key}' contains unusual characters`,
+        content: line
+      });
+    }
+
+    // Check for duplicate
+    if (key in result.variables) {
+      result.warnings.push({
+        line: lineNum,
+        message: `Duplicate variable '${key}' (previous at line ${result.lineInfo[key]})`,
+        content: line
+      });
+    }
+
+    // Parse value (handle quotes)
+    value = parseValue(value);
+
+    result.variables[key] = value;
+    result.lineInfo[key] = lineNum;
+  }
+
+  return result;
+}
+
+/**
+ * Parse a value, handling quotes and escapes
+ * @param {string} raw - Raw value string
+ * @returns {string} Parsed value
+ */
+function parseValue(raw) {
+  let value = raw;
+
+  // Remove inline comments (but not if inside quotes)
+  if (!value.startsWith('"') && !value.startsWith("'")) {
+    const hashIndex = value.indexOf(' #');
+    if (hashIndex !== -1) {
+      value = value.slice(0, hashIndex);
+    }
+  }
+
+  value = value.trim();
+
+  // Handle quoted values
+  if ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+    // Handle escape sequences in double quotes
+    if (raw.trim().startsWith('"')) {
+      value = value.replace(/\\n/g, '\n')
+                   .replace(/\\r/g, '\r')
+                   .replace(/\\t/g, '\t')
+                   .replace(/\\\\/g, '\\')
+                   .replace(/\\"/g, '"');
+    }
+  }
+
+  return value;
+}
+
+/**
+ * Read and parse a .env file
+ * @param {string} filePath - Path to file
+ * @returns {Object} Parsed result
+ */
+function readEnvFile(filePath) {
+  const absolutePath = path.resolve(filePath);
+
+  if (!fs.existsSync(absolutePath)) {
+    return {
+      exists: false,
+      path: absolutePath,
+      variables: {},
+      errors: [{ message: `File not found: ${absolutePath}` }],
+      warnings: [],
+      lineInfo: {}
+    };
+  }
+
+  const content = fs.readFileSync(absolutePath, 'utf8');
+  const result = parseEnv(content);
+  result.exists = true;
+  result.path = absolutePath;
+
+  return result;
+}
+
+/**
+ * Compare two env files
+ * @param {string} envPath - Path to .env file
+ * @param {string} examplePath - Path to .env.example file
+ * @returns {Object} Comparison result
+ */
+function compare(envPath, examplePath) {
+  const env = readEnvFile(envPath);
+  const example = readEnvFile(examplePath);
+
+  const result = {
+    env,
+    example,
+    missing: [],      // In example but not in env
+    extra: [],        // In env but not in example
+    empty: [],        // In both but empty in env
+    different: []     // Different values (if example has values)
+  };
+
+  if (!env.exists || !example.exists) {
+    return result;
+  }
+
+  const envKeys = new Set(Object.keys(env.variables));
+  const exampleKeys = new Set(Object.keys(example.variables));
+
+  // Find missing (in example but not in env)
+  for (const key of exampleKeys) {
+    if (!envKeys.has(key)) {
+      result.missing.push({
+        key,
+        exampleValue: example.variables[key],
+        line: example.lineInfo[key]
+      });
+    }
+  }
+
+  // Find extra (in env but not in example)
+  for (const key of envKeys) {
+    if (!exampleKeys.has(key)) {
+      result.extra.push({
+        key,
+        value: env.variables[key],
+        line: env.lineInfo[key]
+      });
+    }
+  }
+
+  // Find empty values
+  for (const key of envKeys) {
+    if (exampleKeys.has(key) && env.variables[key] === '') {
+      result.empty.push({
+        key,
+        line: env.lineInfo[key]
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validate an env file
+ * @param {string} filePath - Path to .env file
+ * @param {Object} options - Validation options
+ * @returns {Object} Validation result
+ */
+function validate(filePath, options = {}) {
+  const { required = [], noEmpty = false } = options;
+
+  const env = readEnvFile(filePath);
+
+  const result = {
+    valid: true,
+    env,
+    issues: []
+  };
+
+  if (!env.exists) {
+    result.valid = false;
+    result.issues.push({
+      type: 'error',
+      message: `File not found: ${filePath}`
+    });
+    return result;
+  }
+
+  // Check for parse errors
+  if (env.errors.length > 0) {
+    result.valid = false;
+    for (const error of env.errors) {
+      result.issues.push({
+        type: 'error',
+        line: error.line,
+        message: error.message
+      });
+    }
+  }
+
+  // Check required variables
+  for (const key of required) {
+    if (!(key in env.variables)) {
+      result.valid = false;
+      result.issues.push({
+        type: 'error',
+        message: `Missing required variable: ${key}`
+      });
+    } else if (env.variables[key] === '') {
+      result.valid = false;
+      result.issues.push({
+        type: 'error',
+        line: env.lineInfo[key],
+        message: `Required variable '${key}' is empty`
+      });
+    }
+  }
+
+  // Check for empty values
+  if (noEmpty) {
+    for (const [key, value] of Object.entries(env.variables)) {
+      if (value === '' && !required.includes(key)) {
+        result.issues.push({
+          type: 'warning',
+          line: env.lineInfo[key],
+          message: `Variable '${key}' is empty`
+        });
+      }
+    }
+  }
+
+  // Add warnings
+  for (const warning of env.warnings) {
+    result.issues.push({
+      type: 'warning',
+      line: warning.line,
+      message: warning.message
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Check an env file against example and validate
+ * @param {string} envPath - Path to .env
+ * @param {Object} options - Check options
+ * @returns {Object} Check result
+ */
+function check(envPath, options = {}) {
+  const {
+    examplePath = null,
+    required = [],
+    noEmpty = false,
+    noExtra = false,
+    strict = false
+  } = options;
+
+  const result = {
+    valid: true,
+    issues: [],
+    summary: {
+      errors: 0,
+      warnings: 0
+    }
+  };
+
+  // First validate the env file
+  const validation = validate(envPath, { required, noEmpty });
+
+  if (!validation.valid) {
+    result.valid = false;
+  }
+
+  result.issues.push(...validation.issues);
+  result.env = validation.env;
+
+  // Then compare with example if provided
+  if (examplePath) {
+    const comparison = compare(envPath, examplePath);
+    result.comparison = comparison;
+
+    // Missing variables are errors
+    for (const item of comparison.missing) {
+      result.valid = false;
+      result.issues.push({
+        type: 'error',
+        message: `Missing variable '${item.key}' (defined in example at line ${item.line})`
+      });
+    }
+
+    // Empty variables are warnings (or errors in strict mode)
+    for (const item of comparison.empty) {
+      const type = strict ? 'error' : 'warning';
+      if (strict) result.valid = false;
+      result.issues.push({
+        type,
+        line: item.line,
+        message: `Variable '${item.key}' is empty`
+      });
+    }
+
+    // Extra variables are warnings (or errors if noExtra)
+    if (noExtra) {
+      for (const item of comparison.extra) {
+        result.valid = false;
+        result.issues.push({
+          type: 'error',
+          line: item.line,
+          message: `Extra variable '${item.key}' not in example`
+        });
+      }
+    }
+  }
+
+  // Count issues
+  for (const issue of result.issues) {
+    if (issue.type === 'error') {
+      result.summary.errors++;
+    } else {
+      result.summary.warnings++;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate a template .env from .env.example
+ * @param {string} examplePath - Path to example file
+ * @param {Object} defaults - Default values to fill in
+ * @returns {string} Generated .env content
+ */
+function generate(examplePath, defaults = {}) {
+  const example = readEnvFile(examplePath);
+
+  if (!example.exists) {
+    throw new Error(`Example file not found: ${examplePath}`);
+  }
+
+  const lines = [];
+
+  for (const [key, value] of Object.entries(example.variables)) {
+    const newValue = key in defaults ? defaults[key] : value;
+    lines.push(`${key}=${newValue}`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Get list of variables from file
+ * @param {string} filePath - Path to env file
+ * @returns {string[]} Variable names
+ */
+function list(filePath) {
+  const env = readEnvFile(filePath);
+  return Object.keys(env.variables);
+}
+
+/**
+ * Get a specific variable value
+ * @param {string} filePath - Path to env file
+ * @param {string} key - Variable name
+ * @returns {string|undefined} Value or undefined
+ */
+function get(filePath, key) {
+  const env = readEnvFile(filePath);
+  return env.variables[key];
+}
+
+module.exports = {
+  parse: parseEnv,
+  parseValue,
+  readEnvFile,
+  compare,
+  validate,
+  check,
+  generate,
+  list,
+  get
+};