Environment Replicator

---
description: Generate docker-compose.yml, seed scripts, and .env.example for local dev
allowed-tools: Bash, Read, Write, Glob, Grep
context:
  - type: command
    command: "cat package.json 2>/dev/null"
  - type: command
    command: "cat docker-compose.yml 2>/dev/null"
---

# Environment Replicator

Analyze the application's code, configuration, and dependencies to generate a complete local development environment setup: `docker-compose.yml` with all required services, `.env.example` with documented variables, seed/migration scripts, and setup instructions.

## Steps

1. **Identify required services.** Scan the codebase for:
   - **Database**: look for connection strings, ORM config (`prisma/schema.prisma`, `drizzle.config.*`, `knexfile.*`, `ormconfig.*`), or driver imports (`pg`, `mysql2`, `mongodb`, `redis`)
   - **Cache**: look for Redis/Memcached client usage (`ioredis`, `redis`, `memcached`)
   - **Message queue**: look for RabbitMQ, Kafka, SQS, or BullMQ imports
   - **Search**: look for Elasticsearch, Meilisearch, or Typesense clients
   - **Object storage**: look for S3/MinIO client usage
   - **Email**: look for SMTP configuration or email service imports (Nodemailer, SendGrid, etc.)
   - **Auth services**: look for OAuth providers, LDAP config, or auth service URLs

2. **Collect all environment variables.** Grep the codebase for:
   - `process.env.*` and `import.meta.env.*` patterns
   - `.env`, `.env.local`, `.env.example` files
   - Config files that reference env vars
   For each variable, determine:
   - Purpose (from context or naming convention)
   - Whether it is a secret (passwords, API keys, tokens)
   - Whether it has a sensible default for local development
   - Which service it connects to

3. **Check for existing Docker setup.** If `docker-compose.yml` already exists:
   - Read it and identify what is already defined
   - Note what is missing based on step 1
   - Generate an enhanced version rather than starting from scratch

4. **Generate docker-compose.yml.** Create a compose file with:
   - **Service for each dependency** identified in step 1
   - Use official images with pinned major versions (e.g., `postgres:16`, `redis:7`)
   - Configure health checks for each service
   - Set up named volumes for data persistence
   - Map ports to conventional local ports
   - Add a depends_on chain reflecting startup order
   - Include the application itself as a service (with `build: .` or `command: npm run dev`) if appropriate
   - Add labels for documentation

5. **Generate .env.example.** Create a documented env file:
   ```
   # =====================
   # Database Configuration
   # =====================
   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_dev
   # DATABASE_URL=mysql://root:root@localhost:3306/myapp_dev  # Uncomment for MySQL

   # =====================
   # Redis Configuration
   # =====================
   REDIS_URL=redis://localhost:6379

   # =====================
   # Authentication
   # =====================
   # Generate with: openssl rand -base64 32
   JWT_SECRET=change-me-in-production

   # =====================
   # External Services (optional for local dev)
   # =====================
   # SENDGRID_API_KEY=
   # STRIPE_SECRET_KEY=
   ```
   Group variables by service, add comments explaining each, provide working defaults for local dev, and clearly mark secrets.

6. **Generate seed scripts.** Based on the database schema:
   - Read migration files or schema definitions
   - Generate a seed script that populates the database with realistic sample data
   - Include admin/test user accounts with documented credentials
   - Add enough data to exercise pagination, search, and filtering features
   - Write the script in the project's language/framework (Prisma seed, SQL file, etc.)

7. **Generate a setup script.** Create a `scripts/setup-dev.sh` that:
   ```bash
   #!/bin/bash
   set -e

   echo "Copying environment template..."
   cp -n .env.example .env

   echo "Starting services..."
   docker compose up -d

   echo "Waiting for database..."
   # Health check loop

   echo "Running migrations..."
   # Project-specific migration command

   echo "Seeding database..."
   # Project-specific seed command

   echo "Development environment ready!"
   ```

8. **Write all files** and provide a summary of what was generated and how to use it.

## Rules

- Never include real secrets, API keys, or production credentials in any generated file.
- Use `localhost` URLs in `.env.example` that match the docker-compose port mappings.
- Pin Docker image versions to major (not `latest`) for reproducibility.
- If a service is optional for development (e.g., email), include it commented out in docker-compose.
- Add a `.dockerignore` file if one does not already exist.
- The setup script must be idempotent — safe to run multiple times.