#!/usr/bin/env python3
# .env Scream Detector - Core detection logic

import re
import sys
from pathlib import Path

def find_missing_vars(error_output, example_path):
    """
    Analyzes error output and .env.example to find missing environment variables.
    
    Args:
        error_output (str): Console error text
        example_path (str): Path to .env.example file
    
    Returns:
        list: Missing environment variable names
    """
    
    # Extract variable names from error messages
    error_patterns = [
        r"undefined variable ['\"]([A-Z_]+)['\"]",
        r"Cannot read property '([A-Z_]+)'",
        r"ENV['\"]([A-Z_]+)['\"] not set",
        r"Missing required variable: ([A-Z_]+)"
    ]
    
    found_in_errors = []
    for pattern in error_patterns:
        matches = re.findall(pattern, error_output, re.IGNORECASE)
        found_in_errors.extend(matches)
    
    # Read expected variables from .env.example
    try:
        with open(example_path, 'r') as f:
            example_content = f.read()
        
        # Extract variable names from .env.example
        example_vars = []
        for line in example_content.split('\n'):
            line = line.strip()
            if line and not line.startswith('#'):
                var_name = line.split('=')[0].strip()
                if var_name:
                    example_vars.append(var_name)
    
        # Find what's missing
        missing_vars = []
        for var in found_in_errors:
            if var in example_vars:
                missing_vars.append(var)
        
        return missing_vars
        
    except FileNotFoundError:
        return ["ERROR: .env.example file not found at " + example_path]

# Example usage:
if __name__ == "__main__":
    # Simulate error output (in practice, pipe your console output here)
    sample_error = """
    Error: Cannot read property 'API_KEY'
    ReferenceError: DATABASE_URL is not defined
    """
    
    missing = find_missing_vars(sample_error, ".env.example")
    
    if missing:
        print("\n🚨 Missing environment variables found:\n")
        for var in missing:
            print(f"  • {var} - Add this to your .env file")
    else:
        print("✅ No missing .env variables detected in the error output")

The Problem: Why Are We Like This?

import re
import os

def detect_missing_env_vars(error_output, example_env_path='.env.example'):
    """
    Analyzes error output and compares with .env.example to find missing variables.
    
    Args:
        error_output (str): Console error message containing undefined variables
        example_env_path (str): Path to .env.example file
    
    Returns:
        list: Missing environment variables with suggested fixes
    """
    
    # Extract potential env var names from error messages
    env_pattern = r"(?:process\.env\.|\$?\{?)([A-Z_][A-Z0-9_]*)(?:\}?)"
    found_vars = re.findall(env_pattern, error_output, re.IGNORECASE)
    
    # Read expected variables from .env.example
    expected_vars = []
    if os.path.exists(example_env_path):
        with open(example_env_path, 'r') as f:
            for line in f:
                line = line.strip()
                if line and not line.startswith('#'):
                    var_name = line.split('=')[0].strip()
                    expected_vars.append(var_name)
    
    # Find what's missing
    missing_vars = []
    for var in found_vars:
        if var in expected_vars and var not in os.environ:
            missing_vars.append({
                'variable': var,
                'fix': f'Add {var}=your_value_here to your .env file',
                'description': 'Found in error but missing from environment'
            })
    
    return missing_vars

# Example usage:
error_msg = """
Error: Cannot read property 'split' of undefined
process.env.API_KEY is not defined
Missing: DATABASE_URL
"""

missing = detect_missing_env_vars(error_msg)
for item in missing:
    print(f"\u26a0\ufe0f Missing: {item['variable']}")
    print(f"   Fix: {item['fix']}\n")

Let's be honest—environment variable errors are the digital equivalent of losing your keys in your own house. You know they're somewhere, the house isn't that big, but suddenly you're checking the freezer because why not? The problem exists because somewhere along the line, we collectively decided that "undefined is not a function" was a perfectly acceptable way to say "hey dummy, you forgot to set your API key."

This isn't just a minor inconvenience—it's a productivity black hole. Junior developers waste hours. Senior developers waste minutes pretending they know exactly what's wrong before secretly checking the .env.example file. Teams lose collective IQ points every time someone says "it works on my machine" while silently praying the problem isn't actually on their machine.

Consider these real scenarios that have caused actual developers to question their life choices:

• "Error: Cannot read property 'split' of undefined" (Translation: Your DATABASE_URL is empty, genius)
• "TypeError: expected string, got undefined" (Translation: You didn't set JWT_SECRET, and now your auth is broken)
• The classic "Connection refused" (Translation: Could be anything! Network issues! Firewall! Or... you forgot to set PORT to something other than undefined)

These errors are so vague they could be fortune cookie messages. "You will encounter unexpected obstacles"—thanks, console, very helpful.

The Solution: Because You Shouldn't Need a PhD in Error Message Interpretation

Enter .env Scream Detector—the tool that does what your error messages should have done in the first place: actually tell you what's wrong. It's like having a sarcastic but brilliant friend looking over your shoulder who says things like "Missing API_KEY - did you think it would magically appear?" and then hands you the exact command to fix it.

Here's how it works at a high level: The tool monitors your console output (whether you're running Node.js, Docker, or any other process that might complain about missing environment variables). When it detects common error patterns—those beautiful, cryptic messages we all know and hate—it cross-references them with your .env.example file (or any template you specify) and identifies exactly which variable is the culprit.

The magic isn't in complex AI or machine learning (though that would be cooler to say in meetings). The magic is in simple pattern matching and actually reading the files that are already in your project. Why didn't we do this years ago? Probably because we were too busy screaming at our terminals.

Despite the humorous approach, this tool solves a real, daily pain point. Onboarding new developers becomes minutes instead of hours. Debugging deployment issues becomes systematic instead of guesswork. And most importantly, you stop feeling like an idiot when the problem was just a missing underscore in a variable name.

How to Use It: Because Reading Documentation is Also Hard

Installation is straightforward because if it weren't, I'd be a hypocrite. The tool is available via npm for your convenience:

npm install -g env-scream-detector
# or if you're a yarn person
# yarn global add env-scream-detector

Basic usage is even simpler. Instead of running your application directly, pipe its output through the detector:

# Before: node app.js
# After:
env-scream app.js

# Or for Docker fans:
docker-compose up | env-scream

Here's a snippet from the main detection logic that shows how simple the pattern matching can be:

// From the actual source code
function detectEnvScream(errorMessage) {
  const patterns = [
    { 
      regex: /API.*KEY.*(undefined|missing)/i, 
      suggestion: 'API_KEY' 
    },
    { 
      regex: /DATABASE.*URL.*(not defined|undefined)/i, 
      suggestion: 'DATABASE_URL' 
    },
    { 
      regex: /JWT.*SECRET.*(required|missing)/i, 
      suggestion: 'JWT_SECRET' 
    }
  ];
  
  for (const pattern of patterns) {
    if (pattern.regex.test(errorMessage)) {
      return `Missing ${pattern.suggestion} - did you check your .env file?`;
    }
  }
  return null;
}

Check out the full source code on GitHub to see all the patterns and the cross-referencing logic with .env.example files. It's open source, so you can add your own patterns for the obscure errors only your specific framework produces.

Key Features That Actually Help

• Monitors console output for common env-related error patterns: Watches for those beautiful, useless error messages we all know and adds actual useful information.
• Cross-references with .env.example files to suggest missing variables: Because the answer is usually in the file you forgot to copy.
• Generates sarcastic but helpful error messages: Like "Missing API_KEY - did you think it would magically appear?" because sometimes shame is a good teacher.
• Auto-suggests .env file fixes with copy-paste ready commands: No more typing errors when you're already frustrated. Just copy, paste, and stop screaming.
• Works with multiple platforms: Node.js, Docker, Python (with the right patterns)—basically anything that outputs to a console and hates you.
• Custom pattern support: Add your own regex patterns for framework-specific errors that make equally little sense.

Conclusion: Stop Screaming, Start Coding

Environment variable errors are the low-hanging fruit of developer productivity. They're simple problems made complex by bad error messages and worse assumptions. .env Scream Detector won't solve all your problems (you still have to write actual code), but it will solve one of the most frustrating and time-wasting problems in modern development.

The benefits are clear: faster onboarding, less debugging time, fewer existential crises when deployments fail. But the real benefit is psychological—you'll finally feel like your tools are working with you instead of against you. And when the tool itself is free and open source, there's no reason not to try it.

Try it out: https://github.com/BoopyCode/env-file-scream

Your terminal will still judge you, but at least now it will tell you why.