claude-mpm 4.25.10__py3-none-any.whl → 5.1.8__py3-none-any.whl

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

@@ -1,260 +0,0 @@
----
-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

@@ -1,315 +0,0 @@
-# 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)