proagents 1.0.0

package/proagents/environments/setup.md

@@ -0,0 +1,420 @@
+# Environment Setup
+
+Guide to setting up and configuring different environments.
+
+---
+
+## Environment Types
+
+| Environment | Purpose | Data | Access |
+|-------------|---------|------|--------|
+| **Local** | Developer workstation | Mock/seed data | Individual |
+| **Development** | Shared development | Synthetic data | Team |
+| **Staging** | Pre-production testing | Production-like | Team + QA |
+| **Production** | Live system | Real data | Restricted |
+
+---
+
+## Local Environment Setup
+
+### Prerequisites
+
+```bash
+# Required tools
+node --version    # >= 18.x
+npm --version     # >= 9.x
+docker --version  # >= 24.x
+git --version     # >= 2.x
+```
+
+### Quick Start
+
+```bash
+# Clone repository
+git clone ${REPO_URL}
+cd project
+
+# Install dependencies
+npm install
+
+# Copy environment file
+cp .env.example .env.local
+
+# Start local services
+docker-compose up -d
+
+# Run database migrations
+npm run db:migrate
+
+# Seed development data
+npm run db:seed
+
+# Start development server
+npm run dev
+```
+
+### Local Environment File
+
+```bash
+# .env.local
+NODE_ENV=development
+
+# Application
+APP_URL=http://localhost:3000
+API_URL=http://localhost:3001
+
+# Database
+DATABASE_URL=postgresql://user:pass@localhost:5432/app_dev
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Auth (development keys)
+JWT_SECRET=dev-secret-key-change-in-production
+SESSION_SECRET=dev-session-secret
+
+# External Services (use mocks)
+USE_MOCK_SERVICES=true
+MOCK_PAYMENT_GATEWAY=true
+
+# Debug
+DEBUG=app:*
+LOG_LEVEL=debug
+```
+
+### Docker Compose for Local
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: app_dev
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7
+    ports:
+      - "6379:6379"
+
+  mailhog:
+    image: mailhog/mailhog
+    ports:
+      - "1025:1025"  # SMTP
+      - "8025:8025"  # Web UI
+
+volumes:
+  postgres_data:
+```
+
+---
+
+## Development Environment Setup
+
+### Cloud Development Environment
+
+```yaml
+# proagents.config.yaml
+environments:
+  development:
+    type: "cloud"
+    provider: "aws"  # or gcp, azure
+
+    infrastructure:
+      compute:
+        type: "ecs-fargate"
+        cpu: 256
+        memory: 512
+
+      database:
+        type: "rds-postgres"
+        instance: "db.t3.micro"
+        storage: 20
+
+      cache:
+        type: "elasticache-redis"
+        node_type: "cache.t3.micro"
+
+    networking:
+      vpc: "dev-vpc"
+      subnets: ["dev-subnet-1", "dev-subnet-2"]
+```
+
+### Development Environment Variables
+
+```bash
+# .env.development
+NODE_ENV=development
+
+# Application
+APP_URL=https://dev.app.example.com
+API_URL=https://dev-api.app.example.com
+
+# Database (from secrets manager)
+DATABASE_URL=${aws:secretsmanager:dev/database/url}
+
+# External Services
+STRIPE_API_KEY=${aws:secretsmanager:dev/stripe/key}
+SENDGRID_API_KEY=${aws:secretsmanager:dev/sendgrid/key}
+
+# Feature Flags
+FEATURE_FLAGS_ENV=development
+ENABLE_DEBUG_ENDPOINTS=true
+```
+
+### Development Access
+
+```yaml
+environments:
+  development:
+    access:
+      allowed_roles: ["developer", "reviewer", "admin"]
+      vpn_required: false
+      ip_whitelist: ["office-ip-range"]
+
+    monitoring:
+      log_level: "debug"
+      metrics_enabled: true
+      error_tracking: true
+```
+
+---
+
+## Staging Environment Setup
+
+### Staging Configuration
+
+```yaml
+environments:
+  staging:
+    type: "cloud"
+    provider: "aws"
+
+    infrastructure:
+      compute:
+        type: "ecs-fargate"
+        cpu: 512
+        memory: 1024
+        replicas: 2
+
+      database:
+        type: "rds-postgres"
+        instance: "db.t3.small"
+        storage: 50
+        multi_az: false
+
+      cache:
+        type: "elasticache-redis"
+        node_type: "cache.t3.small"
+
+    # Mirror production settings
+    settings:
+      ssl_enabled: true
+      rate_limiting: true
+      cdn_enabled: true
+```
+
+### Staging Data Strategy
+
+```yaml
+environments:
+  staging:
+    data:
+      strategy: "production_subset"
+
+      # Anonymize production data
+      anonymization:
+        enabled: true
+        rules:
+          - table: "users"
+            fields:
+              email: "faker.email"
+              name: "faker.name"
+              phone: "mask"
+
+          - table: "payments"
+            fields:
+              card_number: "mask"
+              cvv: "remove"
+
+      # Refresh schedule
+      refresh:
+        schedule: "weekly"
+        day: "sunday"
+        time: "02:00"
+```
+
+### Staging Environment Variables
+
+```bash
+# .env.staging
+NODE_ENV=staging
+
+# Application
+APP_URL=https://staging.app.example.com
+API_URL=https://staging-api.app.example.com
+
+# Database
+DATABASE_URL=${aws:secretsmanager:staging/database/url}
+
+# External Services (sandbox/test accounts)
+STRIPE_API_KEY=${aws:secretsmanager:staging/stripe/key}
+STRIPE_WEBHOOK_SECRET=${aws:secretsmanager:staging/stripe/webhook}
+
+# Feature Flags
+FEATURE_FLAGS_ENV=staging
+ENABLE_DEBUG_ENDPOINTS=false
+
+# Monitoring
+SENTRY_DSN=${aws:secretsmanager:staging/sentry/dsn}
+DATADOG_API_KEY=${aws:secretsmanager:staging/datadog/key}
+```
+
+---
+
+## Production Environment Setup
+
+### Production Infrastructure
+
+```yaml
+environments:
+  production:
+    type: "cloud"
+    provider: "aws"
+    region: "us-east-1"
+
+    infrastructure:
+      compute:
+        type: "ecs-fargate"
+        cpu: 1024
+        memory: 2048
+        replicas:
+          min: 3
+          max: 10
+        autoscaling:
+          cpu_threshold: 70
+          memory_threshold: 80
+
+      database:
+        type: "rds-postgres"
+        instance: "db.r5.large"
+        storage: 500
+        multi_az: true
+        read_replicas: 2
+        backup_retention: 30
+
+      cache:
+        type: "elasticache-redis"
+        node_type: "cache.r5.large"
+        cluster_mode: true
+        replicas: 2
+
+    # High availability
+    ha:
+      multi_region: true
+      dr_region: "us-west-2"
+      failover_mode: "automatic"
+
+    # Security
+    security:
+      waf_enabled: true
+      ddos_protection: true
+      encryption_at_rest: true
+      encryption_in_transit: true
+```
+
+### Production Access Controls
+
+```yaml
+environments:
+  production:
+    access:
+      allowed_roles: ["deployer", "admin"]
+      vpn_required: true
+      mfa_required: true
+      ip_whitelist: ["vpn-exit-ips"]
+
+      # Audit all access
+      audit:
+        enabled: true
+        log_all_commands: true
+        retention: "2 years"
+
+    # Deployment controls
+    deployment:
+      require_approval: true
+      approvers: ["tech-lead", "sre"]
+      deployment_window:
+        days: ["tuesday", "wednesday", "thursday"]
+        hours: ["10:00", "16:00"]
+        timezone: "America/New_York"
+```
+
+---
+
+## Environment Setup Commands
+
+```bash
+# Setup new environment
+proagents env setup development
+
+# Verify environment configuration
+proagents env verify staging
+
+# Sync environment variables
+proagents env sync --from development --to staging
+
+# Show environment status
+proagents env status production
+
+# Compare environments
+proagents env diff staging production
+
+# Export environment config
+proagents env export staging > staging-config.yaml
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Database connection failed | Wrong credentials | Verify DATABASE_URL |
+| Service unavailable | Container not running | Check docker-compose logs |
+| SSL errors | Certificate mismatch | Update certificates |
+| Slow performance | Resource limits | Increase CPU/memory |
+
+### Health Checks
+
+```bash
+# Check all services
+proagents env health development
+
+# Check specific service
+proagents env health staging --service api
+
+# Detailed diagnostics
+proagents env diagnose production
+```
+
+---
+
+## Best Practices
+
+1. **Parity**: Keep environments as similar as possible
+2. **Secrets**: Never commit secrets to version control
+3. **Infrastructure as Code**: Version control all configurations
+4. **Documentation**: Document environment-specific quirks
+5. **Access Control**: Restrict production access
+6. **Monitoring**: Monitor all environments, not just production

package/proagents/examples/README.md

@@ -0,0 +1,55 @@
+# Examples
+
+Complete workflow examples for different project types.
+
+---
+
+## Overview
+
+Real-world examples showing how to use ProAgents for different project types and scenarios.
+
+## Project Type Examples
+
+| Example | Description |
+|---------|-------------|
+| [Web Frontend (React)](./web-frontend-react/) | React SPA with component library |
+| [Full-Stack (Next.js)](./fullstack-nextjs/) | Next.js with API routes |
+| [Mobile (React Native)](./mobile-react-native/) | Cross-platform mobile app |
+| [Backend (Node.js)](./backend-nodejs/) | Express/Node.js API |
+
+## Each Example Includes
+
+- Complete workflow walkthrough
+- Phase-by-phase breakdown
+- Sample prompts and outputs
+- Configuration examples
+- Common patterns
+
+## Conversation Examples
+
+See how ProAgents works in practice with full AI-user conversation examples:
+
+| Example | Feature Built |
+|---------|---------------|
+| [React Conversation](./web-frontend-react/complete-conversation.md) | Notifications system with real-time updates |
+| [Node.js Conversation](./backend-nodejs/complete-conversation.md) | Tiered rate limiting system |
+
+These show the actual back-and-forth interaction between user and AI.
+
+## Using Examples
+
+```bash
+# View example for your project type
+proagents example show react
+
+# Initialize with example config
+proagents init --template react
+```
+
+## Contributing Examples
+
+To add a new example:
+1. Create directory: `examples/[type]/`
+2. Add `workflow-example.md`
+3. Include sample configs
+4. Document all phases

package/proagents/examples/backend-nodejs/README.md

@@ -0,0 +1,188 @@
+# Backend Node.js Example
+
+Complete walkthrough of ProAgents workflow for a Node.js backend API service.
+
+---
+
+## Overview
+
+This example demonstrates how to use ProAgents to build features in a Node.js backend application. It covers API design, database operations, authentication, and service architecture.
+
+---
+
+## Project Type
+
+- **Runtime:** Node.js 18+
+- **Framework:** Express / Fastify
+- **Language:** TypeScript
+- **Database:** PostgreSQL + Prisma
+- **Testing:** Vitest + Supertest
+
+---
+
+## Files in This Example
+
+| File | Description |
+|------|-------------|
+| [workflow-example.md](./workflow-example.md) | Step-by-step workflow phases |
+| [complete-conversation.md](./complete-conversation.md) | Full AI conversation example |
+| [proagents.config.yaml](./proagents.config.yaml) | Project-specific configuration |
+
+---
+
+## What You'll Learn
+
+### 1. Backend Analysis
+- Understanding service architecture
+- API endpoint mapping
+- Database schema analysis
+- Middleware and authentication flows
+
+### 2. API Design
+- RESTful endpoint design
+- Request/response schemas (Zod)
+- Error handling patterns
+- API documentation (OpenAPI)
+
+### 3. Implementation
+- Controller and service layers
+- Database operations
+- Input validation
+- Error handling and logging
+
+### 4. Testing
+- Unit tests for services
+- Integration tests for API routes
+- Database testing with transactions
+- 85% coverage target for backend
+
+---
+
+## Quick Start
+
+```bash
+# Copy configuration to your Node.js project
+cp proagents.config.yaml /path/to/your/nodejs-project/
+
+# Start a new feature
+proagents feature start "Add user preferences API"
+```
+
+---
+
+## Example Feature: Preferences API
+
+The complete-conversation.md shows building a preferences API:
+- CRUD endpoints for user preferences
+- Database schema and migrations
+- Input validation with Zod
+- Comprehensive error handling
+
+---
+
+## Key Patterns Demonstrated
+
+### Project Structure
+```
+src/
+├── controllers/      # Request handlers
+│   └── users.controller.ts
+├── services/         # Business logic
+│   └── users.service.ts
+├── models/           # Database models
+│   └── user.model.ts
+├── routes/           # Route definitions
+│   └── users.routes.ts
+├── middleware/       # Express middleware
+│   ├── auth.ts
+│   ├── validation.ts
+│   └── error-handler.ts
+├── schemas/          # Zod validation schemas
+│   └── user.schema.ts
+├── utils/            # Utilities
+└── types/            # TypeScript types
+```
+
+### Layered Architecture
+```
+Request → Route → Controller → Service → Database
+                      ↓
+                  Validation
+                      ↓
+                  Response
+```
+
+---
+
+## Configuration Highlights
+
+```yaml
+# From proagents.config.yaml
+project:
+  type: "backend"
+  framework: "express"
+
+database:
+  orm: "prisma"
+  require_migrations: true
+
+api:
+  versioning: "url"  # /api/v1/...
+  documentation: "openapi"
+
+testing:
+  framework: "vitest"
+  coverage_threshold: 85
+  integration_tests: true
+
+security:
+  scan_dependencies: true
+  require_auth_review: true
+
+checkpoints:
+  after_analysis: true    # Review existing patterns
+  after_design: true      # Review API design
+  before_deployment: true # Security review
+```
+
+---
+
+## API Design Workflow
+
+```bash
+# ProAgents guides you through:
+1. Define endpoint structure
+2. Create Zod schemas for validation
+3. Design error responses
+4. Generate OpenAPI documentation
+5. Implement with tests
+```
+
+---
+
+## Security Considerations
+
+### Authentication
+- JWT token validation
+- Role-based access control
+- Rate limiting
+
+### Input Validation
+- Zod schema validation
+- SQL injection prevention
+- XSS protection
+
+### Logging & Monitoring
+- Request logging
+- Error tracking
+- Performance metrics
+
+---
+
+## Related Resources
+
+- [Node.js Scaffolding Template](../../scaffolding/nodejs/)
+- [API Versioning Guide](../../api-versioning/)
+- [Database Migrations](../../database/)
+- [Security Scanning](../../security/)
+- [Contract Testing](../../contract-testing/)