/audit-env-variables

name: audit-env-variables
description: Analyze environment variables in JavaScript/TypeScript projects. Identifies unused variables, infers permission scopes, detects specific services (Stripe, AWS, Supabase), and documents code paths. Includes optional cleanup of unused variables with regression detection. Use when auditing .env files, reviewing security, or documenting project configuration.
argument-hint: "[output-path] [--cleanup]"
allowed-tools: [Read, Grep, Glob, Bash, Write, Edit, AskUserQuestion]

<objective> Perform a comprehensive audit of environment variables in a JS/TS project:

1. **Discovery** - Find all env files and code references 2. **Usage Analysis** - Identify which variables are used vs unused 3. **Service Detection** - Recognize services (Stripe, AWS, Supabase, etc.) and their permission implications 4. **Code Path Mapping** - Document where each variable is used in the codebase 5. **Report Generation** - Output a structured markdown document 6. **Cleanup** (optional) - Safely remove unused variables with user confirmation 7. **Regression Prevention** - Validate no regressions via build/test validation with automatic rollback </objective>

<quick_start> **Audit only (default):** 1. Scan for `.env*` files in project root 2. Grep codebase for `process.env.`, `import.meta.env.`, and destructured env patterns 3. Cross-reference declared vs used variables 4. Identify services by naming patterns and categorize permissions 5. Generate markdown report using the template

**With cleanup (`--cleanup` flag):** 6. Check for dynamic access patterns that might hide usage 7. Present unused variables and get user confirmation 8. Create backups, remove confirmed variables 9. Run build/tests to detect regressions 10. Auto-rollback if regressions detected </quick_start>

<process>

Step 1: Discover Environment Files

Find all env-related files:

find . -maxdepth 2 -name ".env*" -o -name "env.d.ts" | grep -v node_modules

Common files:

• `.env` - Local development
• `.env.local` - Local overrides
• `.env.development` / `.env.production` - Environment-specific
• `.env.example` - Template for required variables

Step 2: Extract Declared Variables

Parse each env file for variable declarations:

Grep pattern: ^[A-Z][A-Z0-9_]+=

Build a list of all declared variables with their source file.

Step 3: Find Code References

Search for environment variable usage patterns:

**Direct access:**

process.env.VARIABLE_NAME
import.meta.env.VARIABLE_NAME
process.env["VARIABLE_NAME"]

**Destructured patterns:**

const { API_KEY, DATABASE_URL } = process.env

**Framework-specific:**

// Next.js public vars
NEXT_PUBLIC_*

// Vite
VITE_*

Use Grep tool with patterns:

process\.env\.([A-Z][A-Z0-9_]+)
import\.meta\.env\.([A-Z][A-Z0-9_]+)

Step 4: Cross-Reference Usage

For each declared variable:

• **Used**: Found in code references
• **Unused**: Declared but no code references found
• **Undeclared**: Referenced in code but not in any env file

Flag potential issues:

• Unused variables (cleanup candidates)
• Undeclared variables (missing from .env.example)
• Variables only in .env but not .env.example (documentation gap)

Step 5: Detect Services and Infer Permissions

Match variable names against known service patterns. See references/service-patterns.md for the complete list.

**Categories:**

• **Database** - Connection strings, credentials
• **Authentication** - JWT secrets, OAuth credentials
• **Payment** - Stripe, payment processor keys
• **Cloud Services** - AWS, GCP, Azure credentials
• **Third-party APIs** - Various service integrations
• **Feature Flags** - Toggle configurations
• **Application Config** - URLs, ports, modes

**Permission levels:**

• **Critical** - Full account access, billing, admin operations
• **High** - Read/write access to user data
• **Medium** - Limited API access, specific operations
• **Low** - Public keys, non-sensitive configuration

Step 6: Map Code Paths

For each used variable, document:

• File path where it's used
• Function/component context
• Purpose (inferred from surrounding code)

Example:

STRIPE_SECRET_KEY
├── src/lib/stripe.ts:15 - Stripe client initialization
├── src/api/webhooks/stripe.ts:8 - Webhook signature verification
└── src/api/checkout/route.ts:23 - Create checkout session

Step 7: Generate Report

Use the template in templates/env-audit-report.md to generate the final document.

Output to: `ENV_AUDIT.md` in project root (or user-specified location)

Step 8: Cleanup Unused Variables (Optional)

**Trigger:** User passes `--cleanup` flag or explicitly requests cleanup after reviewing the audit report.

8.1 Present Cleanup Candidates

Display unused variables with context:

UNUSED VARIABLES (candidates for removal):

1. OLD_API_KEY (.env, .env.local)
   - Last modified: [file date]
   - No code references found

2. DEPRECATED_SERVICE_URL (.env)
   - Last modified: [file date]
   - No code references found

8.2 Dynamic Access Check

Before confirming removal, search for dynamic access patterns that grep may have missed:

// These patterns indicate variables might be used dynamically:
process.env[variableName]        // Dynamic key access
process.env[`${prefix}_KEY`]     // Template literal access
Object.keys(process.env)         // Iteration over all env vars
{ ...process.env }               // Spread operator

Use Grep with patterns:

process\.env\[
Object\.keys\(process\.env\)
Object\.entries\(process\.env\)
\.\.\.process\.env

**If dynamic access patterns found:** Flag affected variables for manual review and warn user.

8.3 User Confirmation

Use AskUserQuestion to confirm each removal:

The following variables appear unused. Select which to remove:

[ ] OLD_API_KEY - Remove from .env, .env.local
[ ] DEPRECATED_SERVICE_URL - Remove from .env
[ ] Skip cleanup

⚠️ Variables will be backed up before rem