# New Rails project
/rails-dev-env new myapp --profile standard

# Existing project (auto-detects Rails/Ruby versions)
/rails-dev-env setup --profile full

/rails-dev-env new <project_name> [options]

/rails-dev-env setup [options]

/rails-dev-env validate

/rails-dev-env status

questions:
  - question: "Which service profile do you need?"
    header: "Profile"
    options:
      - label: "Standard (Recommended)"
        description: "Rails, PostgreSQL, Redis, Sidekiq, Mailpit + Playwright/Selenium (E2E ready)"
      - label: "Minimal"
        description: "Rails, PostgreSQL, Redis only (no E2E testing)"
      - label: "Full"
        description: "Standard + AWS mocking (LocalStack), API mocking (WireMock), Dozzle"
      - label: "Custom"
        description: "Select individual services"

  - question: "Which Rails version?"
    header: "Rails"
    options:
      - label: "Rails 8.1 (Recommended)"
        description: "Latest stable (requires Ruby 3.4+)"
      - label: "Rails 8.0"
        description: "Propshaft, Import Maps, Solid Queue (Ruby 3.2+)"
      - label: "Rails 7.2"
        description: "Stable with Hotwire, good gem compatibility"
      - label: "Other"
        description: "Specify version manually"

from scripts.detect_project import analyze_project

analysis = analyze_project(project_path)
# Returns: ProjectAnalysis with rails_version, ruby_version,
#          database_adapter, existing_docker, detected_services

from scripts.allocate_ports import allocate_port, PORT_RANGES

ports = {}
for service, (start, end) in PORT_RANGES.items():
    ports[service] = allocate_port(
        env_name=project_name,
        service=service,
        start_port=start,
        end_port=end
    )

from scripts.generate_templates import EnvironmentConfig, generate_all
import secrets

config = EnvironmentConfig(
    project_name=project_name,
    project_path=project_path,
    rails_version=(8, 1, 2),
    ruby_version="3.4.1",  # CRITICAL: Rails 8.1+ requires Ruby 3.4+
    node_version="20",
    bundler_version="2.5.0",
    profile="standard",
    services=["postgres", "redis", "sidekiq", "mailpit"],
    ports=ports,
    features={"action_cable": True, "active_storage": True},
    secret_key_base=secrets.token_hex(32),
    generated_at=datetime.now().isoformat(),
    skill_version="1.0.0"
)

result = generate_all(config, project_path)

project/
├── Dockerfile
├── Dockerfile.playwright
├── docker-compose.yml
├── .env
├── .env.template
├── bin/
│   ├── dev-setup.sh
│   ├── dev-start.sh
│   ├── dev-stop.sh
│   ├── dev-status.sh
│   ├── dev-logs.sh
│   ├── dev-reset.sh
│   └── dev-rollback.sh
└── .devcontainer/
    └── devcontainer.json

from scripts.validate_environment import run_all_validations

report = run_all_validations(project_path)
if not report.all_passed:
    # Report issues and fix recommendations
    for result in report.results:
        if not result.passed:
            print(f"Issue: {result.message}")
            for fix in result.suggestions:
                print(f"  Fix: {fix}")

# Run database setup and seeding
./bin/dev-setup.sh  # Creates and migrates database
docker compose exec app rails db:seed

# db/seeds.rb

# ═══════════════════════════════════════════════════════════════════════════
# PRODUCTION-CRITICAL DATA (Required for application to function)
# ═══════════════════════════════════════════════════════════════════════════

puts "🔧 Loading production-critical data..."

# System roles that the application requires
Role.find_or_create_by!(name: 'admin') { |r| r.permissions = ['all'] }
Role.find_or_create_by!(name: 'user') { |r| r.permissions = ['read', 'write'] }

# Required configuration records
Setting.find_or_create_by!(key: 'app_name') { |s| s.value = 'MyApp' }

# Default categories, statuses, etc.
Status.find_or_create_by!(name: 'active')
Status.find_or_create_by!(name: 'inactive')

puts "✅ Production-critical data loaded"

# ═══════════════════════════════════════════════════════════════════════════
# TEST/DEMO DATA (Development and testing convenience)
# ═══════════════════════════════════════════════════════════════════════════

if Rails.env.development? || Rails.env.test?
  puts "🧪 Loading test/demo data..."

  # Demo admin user
  admin = User.find_or_create_by!(email: 'admin@example.com') do |u|
    u.password = 'password123'
    u.role = Role.find_by(name: 'admin')
  end

  # Sample data for testing
  5.times do |i|
    User.find_or_create_by!(email: "user#{i}@example.com") do |u|
      u.password = 'password123'
      u.role = Role.find_by(name: 'user')
    end
  end

  # Add realistic demo data using Faker if available
  if defined?(Faker)
    10.times do
      Project.create!(
        name: Faker::App.name,
        description: Faker::Lorem.paragraph,
        user: User.all.sample
      )
    end
  end

  puts "✅ Test/demo data loaded"
end

from scripts.allocate_ports import allocate_port, is_port_available, PORT_RANGES

# Smart port allocation to avoid conflicts with other running dev servers
rails_port = ports.get('rails', 3000)

# Check if allocated port is still available (another server may have started)
if not is_port_available(rails_port):
    # Find next available port in range
    rails_port = allocate_port(
        env_name=project_name,
        service='rails',
        start_port=PORT_RANGES['rails'][0],
        end_port=PORT_RANGES['rails'][1]
    )
    print(f"⚠️  Port conflict detected. Allocated new port: {rails_port}")

# Start the development server
subprocess.run(['./bin/dev-start.sh'], check=True)

# Example: Running multiple projects
# Project A: Rails on 3000, PostgreSQL on 5432
# Project B: Rails on 3001, PostgreSQL on 5433
# Project C: Rails on 3002, PostgreSQL on 5434

🚀 Starting development server...
📍 Port allocation: Rails=3001, PostgreSQL=5433, Redis=6380
⚡ Server ready at http://localhost:3001

## ✅ Rails Development Environment Created & Running

**Project:** {{ project_name }}
**Profile:** {{ profile }}
**Rails:** {{ rails_version }} | **Ruby:** {{ ruby_version }}

### 🚀 Your Server is Already Running!

The development server started automatically after build completion.

**🔌 Allocated Ports** (smart allocation avoids conflicts with other running servers):
- Rails: http://localhost:{{ ports.rails }}
{% if has_mailpit %}
- Mailpit: http://localhost:{{ ports.mailpit_web }}
{% endif %}
{% if has_playwright %}
- Playwright CDP: ws://localhost:{{ ports.playwright_cdp }}
{% endif %}
{% if has_selenium %}
- Selenium Hub: http://localhost:{{ ports.selenium }}
{% endif %}
{% if has_dozzle %}
- Logs: http://localhost:{{ ports.dozzle }}
{% endif %}

### 🧪 Database Pre-Populated

Your database has been initialized with:
- ✅ Production-critical data (roles, settings, configurations)
- ✅ Test/demo data (sample users, demo records)

Demo credentials: `admin@example.com` / `password123`

### 🧪 E2E Testing Ready (Standard+ Profile)

Browser automation is fully configured:
```bash
# Run system tests with Playwright
rails test:system

# Run with headed browser (visible)
HEADED=true rails test:system

# Run with Selenium
SELENIUM=true rails test:system

---

## Workflow: Setup Existing Project

### Phase 1: Detect Project Configuration

```python
analysis = analyze_project(project_path)

if analysis.rails_version:
    info(f"Detected Rails {'.'.join(map(str, analysis.rails_version))}")
if analysis.ruby_version:
    info(f"Detected Ruby {analysis.ruby_version}")
if analysis.existing_docker:
    warn("Existing Docker configuration found")
    # Ask user about overwrite

questions:
  - question: "Which services do you need?"
    header: "Services"
    multiSelect: true
    options:
      - label: "PostgreSQL"
        description: "Primary database"
      - label: "Redis"
        description: "Caching, sessions, Action Cable"
      - label: "Sidekiq"
        description: "Background job processing"
      - label: "Mailpit"
        description: "Email testing"
      - label: "Browser Automation (Playwright + Selenium)"
        description: "Full E2E testing: Chromium, Firefox, WebKit, headed/headless modes"
      - label: "LocalStack"
        description: "AWS service mocking (S3, SQS, SNS)"
      - label: "WireMock"
        description: "API mocking"
      - label: "Dozzle"
        description: "Real-time log viewer"

if not is_port_available(port):
    # Find next available port in range
    port = allocate_port(env_name, service, start, end)

⚠️ Project uses Ruby 3.2.2 but 3.4.1 requested.
   Using detected version for compatibility.

❌ ERROR: Rails 8.1.x requires Ruby 3.4+

   Rails 8.1 uses anonymous rest parameter syntax (`**`) which is only
   available in Ruby 3.4.0 and later. Ruby 3.3.x will fail with:

   syntax error, unexpected tPOW, expecting ')'
       def foo(**)
              ^~

   FIX: Update Ruby version to 3.4.1 or use Rails 8.0.x

allocate_port(env_name, service, start_port, end_port) -> int
release_ports(env_name) -> None
get_allocated_ports(env_name) -> Dict[str, int]
is_port_available(port) -> bool
cleanup_stale_allocations() -> int

analyze_project(project_path) -> ProjectAnalysis
detect_rails_version(project_path) -> Optional[Tuple[int, int, int]]
detect_ruby_version(project_path) -> Optional[str]
detect_database_config(project_path) -> Dict
detect_services(project_path) -> List[str]

generate_all(config: EnvironmentConfig, output_path) -> GenerationResult
create_context(config) -> Dict[str, Any]
render_template(template_name, context) -> str

run_all_validations(project_path) -> ValidationReport
validate_compose_syntax(compose_path) -> ValidationResult
validate_ports(ports) -> ValidationResult
test_service_connectivity(service, host, port) -> bool