claude-mpm 5.4.59__py3-none-any.whl → 5.4.64__py3-none-any.whl

claude_mpm/skills/bundled/infrastructure/env-manager/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: env-manager
+description: Environment variable validation, synchronization, and management across local development, CI/CD, and deployment platforms
+version: 1.0.0
+category: infrastructure
+progressive_disclosure:
+  entry_point:
+    summary: "Validate, synchronize, and secure environment variables across local dev, CI/CD, and deployment platforms with framework-specific support"
+    when_to_use: "When managing .env files, deploying to Vercel/Railway/Heroku, syncing with secret managers, or troubleshooting env-related issues"
+    quick_start: "1. Validate local .env 2. Check security 3. Sync to platform 4. Verify deployment 5. Generate documentation"
+  references:
+    - validation.md
+    - security.md
+    - synchronization.md
+    - frameworks.md
+    - troubleshooting.md
+author: Claude MPM Team
+license: MIT
+requires_tools:
+  - bash
+  - python
+tags:
+  - environment-variables
+  - deployment
+  - security
+  - devops
+  - nextjs
+  - vercel
+  - railway
+context_limit: 800
+---
+
+# Environment Variable Manager
+
+## Overview
+
+Manage environment variables systematically across local development, CI/CD pipelines, and deployment platforms. Prevent common issues like missing variables, exposed secrets, platform misconfigurations, and framework-specific gotchas.
+
+**Core capabilities:**
+- **Validation**: Check structure, completeness, naming conventions
+- **Security**: Scan for exposed secrets, validate .gitignore coverage
+- **Synchronization**: Sync with deployment platforms and secret managers
+- **Framework Support**: Next.js, Express, Flask, Django patterns
+- **Documentation**: Auto-generate .env.example and setup guides
+
+## When to Use This Skill
+
+Activate when:
+- Setting up new project environment configuration
+- Deploying to Vercel, Railway, Heroku, or other platforms
+- Troubleshooting "works locally but not in production"
+- Managing secrets across multiple environments
+- Syncing variables with 1Password, AWS Secrets Manager
+- Creating .env.example documentation
+- Onboarding new developers (environment setup)
+- Migrating between deployment platforms
+- Framework-specific env configuration (Next.js NEXT_PUBLIC_ prefix)
+
+## Core Principles
+
+1. **Never Log Secrets**: All operations must NEVER display actual secret values
+2. **Validate Before Deploy**: Catch env issues locally, not in production
+3. **Framework-Aware**: Respect framework conventions (Next.js, Express, Flask)
+4. **Platform-Specific**: Generate correct configs for each deployment platform
+5. **Security First**: Scan for exposed secrets, validate .gitignore
+
+## Quick Start
+
+### Validation Workflow
+```bash
+# 1. Check local .env structure
+python scripts/validate_env.py .env
+
+# 2. Check for missing variables
+python scripts/validate_env.py .env --compare .env.example
+
+# 3. Validate naming conventions
+python scripts/validate_env.py .env --framework nextjs
+
+# 4. Check for duplicates
+python scripts/validate_env.py .env --check-duplicates
+```
+
+### Security Workflow
+```bash
+# 1. Scan for exposed secrets in code
+python scripts/scan_exposed.py --scan-code
+
+# 2. Check .gitignore coverage
+python scripts/scan_exposed.py --check-gitignore
+
+# 3. Validate secret formats
+python scripts/scan_exposed.py --validate-formats .env
+```
+
+### Synchronization Workflow
+```bash
+# 1. Compare local vs platform
+python scripts/sync_secrets.py --platform vercel --compare
+
+# 2. Generate platform config
+python scripts/sync_secrets.py --platform vercel --generate
+
+# 3. Sync to platform (dry-run first)
+python scripts/sync_secrets.py --platform vercel --sync --dry-run
+
+# 4. Actual sync
+python scripts/sync_secrets.py --platform vercel --sync
+```
+
+### Documentation Workflow
+```bash
+# Generate .env.example from .env
+python scripts/validate_env.py .env --generate-example
+
+# Generate setup documentation
+python scripts/validate_env.py .env --generate-docs
+```
+
+## Navigation
+
+For detailed workflows and patterns:
+- **[Validation](references/validation.md)**: Complete validation workflows and checks
+- **[Security](references/security.md)**: Secret scanning and security patterns
+- **[Synchronization](references/synchronization.md)**: Platform sync and secret manager integration
+- **[Frameworks](references/frameworks.md)**: Framework-specific patterns (Next.js, Express, Flask)
+- **[Troubleshooting](references/troubleshooting.md)**: Common issues and solutions
+
+## Framework-Specific Quick Reference
+
+### Next.js
+```bash
+# Validate Next.js env structure
+# - NEXT_PUBLIC_* for client-side vars
+# - Check .env.local, .env.production precedence
+python scripts/validate_env.py .env --framework nextjs
+
+# Files to manage:
+# - .env.local (local development, gitignored)
+# - .env.production (production, usually from platform)
+# - .env (shared defaults, committed)
+# - .env.example (documentation, committed)
+```
+
+### Express/Node.js
+```bash
+# Validate Node.js env structure
+python scripts/validate_env.py .env --framework nodejs
+
+# Standard structure:
+# - process.env.NODE_ENV
+# - process.env.PORT
+# - process.env.DATABASE_URL
+```
+
+### Python/Flask
+```bash
+# Validate Python env structure
+python scripts/validate_env.py .env --framework python
+
+# Standard structure:
+# - FLASK_APP
+# - FLASK_ENV
+# - DATABASE_URL (SQLAlchemy format)
+```
+
+## Platform-Specific Quick Reference
+
+### Vercel
+```bash
+# Generate vercel.json env config
+python scripts/sync_secrets.py --platform vercel --generate
+
+# Sync to Vercel project
+python scripts/sync_secrets.py --platform vercel --sync
+
+# Respects NEXT_PUBLIC_ prefix for client-side vars
+```
+
+### Railway
+```bash
+# Generate Railway config
+python scripts/sync_secrets.py --platform railway --generate
+
+# Sync to Railway project
+python scripts/sync_secrets.py --platform railway --sync
+```
+
+### Heroku
+```bash
+# Generate Heroku config
+python scripts/sync_secrets.py --platform heroku --generate
+
+# Sync via Heroku CLI
+python scripts/sync_secrets.py --platform heroku --sync
+```
+
+## Key Reminders
+
+- **NEVER log actual secret values** - Always mask/redact in output
+- **Validate before every deployment** - Catch issues locally
+- **Use .env.example for documentation** - Keep it updated
+- **Framework conventions matter** - Next.js NEXT_PUBLIC_, Django DJANGO_SETTINGS_MODULE
+- **Platform-specific quirks exist** - Vercel auto-exposes NEXT_PUBLIC_*, Railway uses exact syntax
+- **Secret managers are your friend** - 1Password, AWS Secrets Manager for team sync
+- **.gitignore is critical** - NEVER commit .env files with secrets
+- **Environment precedence can be tricky** - Know your framework's loading order
+
+## Common Validation Checks
+
+### Structure Validation
+- [ ] No empty values (except explicitly allowed)
+- [ ] No inline comments (some parsers don't support)
+- [ ] Proper quoting for values with spaces
+- [ ] No duplicate keys
+- [ ] Valid key naming (UPPERCASE_WITH_UNDERSCORES)
+
+### Security Validation
+- [ ] No exposed secrets in code
+- [ ] .env files in .gitignore
+- [ ] No secrets in git history
+- [ ] API keys match expected format
+- [ ] No hardcoded URLs with credentials
+
+### Framework Validation (Next.js)
+- [ ] NEXT_PUBLIC_* for client-side vars only
+- [ ] No secrets in NEXT_PUBLIC_* vars
+- [ ] .env.local exists for local secrets
+- [ ] .env.example documents all vars
+
+### Platform Validation (Vercel)
+- [ ] All required vars defined
+- [ ] No conflicts between environments
+- [ ] Correct variable names (Vercel conventions)
+- [ ] Build-time vs runtime vars separated
+
+## Integration with Other Skills
+
+### Related Skills
+- **docker-containerization** - Environment variables in containers
+- **security-scanning** - Broader security checks including secrets
+- **nextjs-local-dev** - Next.js specific development patterns
+- **systematic-debugging** - Debug env-related issues
+
+### Workflow Integration
+```
+1. Developer creates .env.local
+2. env-manager validates structure
+3. env-manager scans for security issues
+4. Developer generates .env.example
+5. Before deploy: env-manager compares local vs platform
+6. env-manager generates platform config
+7. Developer reviews and confirms sync
+8. env-manager syncs to platform
+9. Deployment proceeds with verified configuration
+```
+
+---
+
+**Lines**: 197 (including frontmatter) ✓ <200

claude_mpm/skills/bundled/infrastructure/env-manager/examples/nextjs-env-structure.md

@@ -0,0 +1,315 @@
+# Next.js Environment Variable Structure
+
+Complete guide to Next.js environment variable management.
+
+## File Structure
+
+```
+my-nextjs-app/
+├── .env                      # Shared defaults (committed)
+├── .env.local               # Local secrets (gitignored)
+├── .env.development         # Development defaults (committed)
+├── .env.development.local   # Local dev overrides (gitignored)
+├── .env.production          # Production defaults (committed)
+├── .env.production.local    # Production secrets (gitignored)
+├── .env.test                # Test environment (committed)
+└── .env.example             # Documentation (committed)
+```
+
+## File Precedence
+
+Next.js loads files in this order (higher = higher precedence):
+
+1. `.env.$(NODE_ENV).local` (e.g., `.env.production.local`)
+2. `.env.local` (not loaded in test environment)
+3. `.env.$(NODE_ENV)` (e.g., `.env.production`)
+4. `.env`
+
+**Example**: In production, if `DATABASE_URL` is defined in both `.env` and `.env.production.local`, the value from `.env.production.local` wins.
+
+## Variable Types
+
+### Client-Side Variables (NEXT_PUBLIC_*)
+
+Exposed to the browser. Must prefix with `NEXT_PUBLIC_`.
+
+```bash
+# .env.local
+NEXT_PUBLIC_API_URL=https://api.example.com
+NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
+NEXT_PUBLIC_SITE_NAME=My Awesome Site
+NEXT_PUBLIC_ENABLE_FEATURE_X=true
+```
+
+**Access in code**:
+```javascript
+// Works in both client and server
+const apiUrl = process.env.NEXT_PUBLIC_API_URL;
+
+// Usage in components
+export default function MyComponent() {
+  return <div>API: {process.env.NEXT_PUBLIC_API_URL}</div>;
+}
+```
+
+**⚠️ Security Warning**: NEVER put secrets in `NEXT_PUBLIC_*` variables!
+
+```bash
+# ❌ WRONG - Secret exposed to browser
+NEXT_PUBLIC_API_SECRET=sk_live_abc123
+
+# ✅ CORRECT - Secret only on server
+API_SECRET=sk_live_abc123
+```
+
+### Server-Side Variables
+
+Only available in server-side code (API routes, getServerSideProps, etc.).
+
+```bash
+# .env.local
+DATABASE_URL=postgres://localhost:5432/mydb
+JWT_SECRET=super-secret-jwt-key-do-not-expose
+STRIPE_SECRET_KEY=sk_live_abc123
+SMTP_PASSWORD=email-password-here
+```
+
+**Access in code**:
+```javascript
+// ✅ Works in API routes
+export default async function handler(req, res) {
+  const dbUrl = process.env.DATABASE_URL;
+  // Use dbUrl...
+}
+
+// ✅ Works in getServerSideProps
+export async function getServerSideProps() {
+  const secret = process.env.JWT_SECRET;
+  // Use secret...
+}
+
+// ❌ Does NOT work in components (browser)
+export default function MyComponent() {
+  const dbUrl = process.env.DATABASE_URL; // undefined!
+}
+```
+
+## Example Files
+
+### .env (Committed - Shared Defaults)
+
+```bash
+# Shared defaults for all environments
+NEXT_PUBLIC_APP_NAME=My Next.js App
+NEXT_PUBLIC_DEFAULT_LOCALE=en
+
+# Database (overridden in .env.local)
+DATABASE_URL=postgres://localhost:5432/dev
+
+# External services (no secrets)
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_abc123
+```
+
+### .env.local (Gitignored - Local Secrets)
+
+```bash
+# Local development secrets
+DATABASE_URL=postgres://localhost:5432/mylocal
+JWT_SECRET=dev-jwt-secret-change-in-production
+STRIPE_SECRET_KEY=sk_test_local_key
+
+# Local overrides
+NEXT_PUBLIC_API_URL=http://localhost:4000/api
+```
+
+### .env.production (Committed - Production Defaults)
+
+```bash
+# Production environment defaults
+NEXT_PUBLIC_API_URL=https://api.production.com
+NEXT_PUBLIC_ANALYTICS_ID=UA-PROD-123456
+
+# These will be overridden by platform env vars
+DATABASE_URL=set-this-in-vercel
+JWT_SECRET=set-this-in-vercel
+```
+
+### .env.example (Committed - Documentation)
+
+```bash
+# Copy this to .env.local and fill in actual values
+
+# Client-side (browser accessible)
+NEXT_PUBLIC_API_URL=https://api.example.com
+NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id
+NEXT_PUBLIC_SITE_NAME=Your Site Name
+
+# Server-side (secrets)
+DATABASE_URL=postgres://user:password@host:5432/database  # pragma: allowlist secret
+JWT_SECRET=your-jwt-secret-32-chars-minimum
+STRIPE_SECRET_KEY=sk_live_your_stripe_key
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=your-email@example.com
+SMTP_PASSWORD=your-smtp-password
+```
+
+## Common Patterns
+
+### Database Configuration
+
+```bash
+# Development (.env.local)
+DATABASE_URL=postgres://localhost:5432/myapp_dev
+
+# Production (Vercel Environment Variables)
+DATABASE_URL=postgres://user:pass@prod-host:5432/myapp_prod  # pragma: allowlist secret
+```
+
+### API Keys
+
+```bash
+# Public keys (client-side)
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_abc123
+
+# Secret keys (server-side only)
+STRIPE_SECRET_KEY=sk_live_xyz789
+```
+
+### Feature Flags
+
+```bash
+# Toggle features
+NEXT_PUBLIC_ENABLE_DARK_MODE=true
+NEXT_PUBLIC_ENABLE_BETA_FEATURES=false
+```
+
+## Deployment to Vercel
+
+### Step 1: Add Environment Variables in Vercel
+
+1. Go to Project Settings → Environment Variables
+2. Add each variable:
+   - **Key**: `DATABASE_URL`
+   - **Value**: `postgres://...`
+   - **Environments**: Production, Preview, Development
+
+### Step 2: Separate Client vs Server Variables
+
+Vercel automatically exposes `NEXT_PUBLIC_*` variables at build time.
+
+```bash
+# Vercel automatically handles:
+NEXT_PUBLIC_API_URL=https://api.example.com  # ✅ Exposed to browser
+
+# Server-only:
+DATABASE_URL=postgres://...  # ✅ Not exposed to browser
+```
+
+### Step 3: Rebuild After Changing NEXT_PUBLIC_ Variables
+
+⚠️ Important: `NEXT_PUBLIC_*` variables are **baked into the build** at build time.
+
+If you change them in Vercel, you must **redeploy**:
+
+```bash
+vercel --prod
+```
+
+## Validation Workflow
+
+### 1. Validate Local Environment
+
+```bash
+# Check structure
+python scripts/validate_env.py .env.local --framework nextjs
+
+# Compare with .env.example
+python scripts/validate_env.py .env.local --compare-with .env.example
+
+# Check for security issues
+python scripts/scan_exposed.py --check-gitignore
+```
+
+### 2. Check File Precedence
+
+```bash
+# List all .env files
+ls -la .env*
+
+# Validate each
+for file in .env*; do
+  echo "=== $file ==="
+  python scripts/validate_env.py $file --framework nextjs
+done
+```
+
+### 3. Sync to Vercel
+
+```bash
+# Compare local vs Vercel
+python scripts/sync_secrets.py --platform vercel --compare
+
+# Sync (dry-run first)
+python scripts/sync_secrets.py --platform vercel --sync --dry-run
+
+# Actually sync
+python scripts/sync_secrets.py --platform vercel --sync --confirm
+```
+
+## Common Issues
+
+### Issue: Variable Undefined in Browser
+
+**Symptom**: `process.env.MY_VAR` is `undefined` in component.
+
+**Solution**: Add `NEXT_PUBLIC_` prefix:
+
+```bash
+# ❌ Wrong
+API_URL=https://api.example.com
+
+# ✅ Correct
+NEXT_PUBLIC_API_URL=https://api.example.com
+```
+
+### Issue: Changed Variable Not Reflected
+
+**Symptom**: Changed `NEXT_PUBLIC_*` variable in Vercel, but app still uses old value.
+
+**Solution**: Redeploy (variables are baked into build):
+
+```bash
+vercel --prod
+```
+
+### Issue: Works Locally, Not in Production
+
+**Symptom**: App works with `.env.local`, fails in production.
+
+**Solution**: Ensure all variables from `.env.local` are set in Vercel:
+
+```bash
+# Compare
+python scripts/sync_secrets.py --platform vercel --compare
+
+# Find missing vars and add them in Vercel UI
+```
+
+## Security Checklist
+
+- [ ] `.env.local` in `.gitignore`
+- [ ] `.env.*.local` in `.gitignore`
+- [ ] No secrets in `NEXT_PUBLIC_*` variables
+- [ ] No `.env` files committed with real secrets
+- [ ] `.env.example` has structure, not actual values
+- [ ] Secrets set directly in Vercel (not in committed files)
+
+## References
+
+- [Next.js Environment Variables Documentation](https://nextjs.org/docs/basic-features/environment-variables)
+- [Vercel Environment Variables](https://vercel.com/docs/environment-variables)
+
+---
+
+**Related**: [validation.md](../references/validation.md) | [security.md](../references/security.md) | [frameworks.md](../references/frameworks.md)