diff --git a/.cursor/rules/port-standardization.mdc b/.cursor/rules/port-standardization.mdc new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/.cursor/rules/port-standardization.mdc @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/.cursor/rules/tools/port-checker.mdc b/.cursor/rules/tools/port-checker.mdc new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/.cursor/rules/tools/port-checker.mdc @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/.env.example b/.env.example index 8c96cac..ac2576d 100644 --- a/.env.example +++ b/.env.example @@ -2,9 +2,20 @@ APP_NAME=MyApp APP_ENV=development APP_DEBUG=true -APP_PORT=8000 APP_SECRET_KEY=replace_with_secure_random_key +# Standardized Port Configuration +# Frontend Ports +FRONTEND_PORT=3000 +DOCS_PORT=3400 + +# Backend Ports +API_PORT=8000 +GRAPHQL_PORT=8080 +WEBSOCKET_PORT=8090 +AUTH_SERVICE_PORT=8100 +FILE_SERVICE_PORT=8200 + # Database Configuration DB_HOST=localhost DB_PORT=5432 @@ -14,6 +25,12 @@ DB_PASSWORD=db_password DB_SSL=false DB_MAX_CONNECTIONS=10 +# Cache Settings +REDIS_HOST=localhost +REDIS_PORT=6379 +REDIS_DB=0 +CACHE_TTL=3600 + # API Keys and External Services OPENAI_API_KEY=your_openai_api_key ANTHROPIC_API_KEY=your_anthropic_api_key @@ -23,7 +40,7 @@ EXTERNAL_SERVICE_URL=https://api.example.com LOG_LEVEL=info LOG_FILE=logs/app.log ENABLE_METRICS=false -METRICS_PORT=9090 +METRICS_PORT=9000 # Security Settings SSL_CERT_PATH= @@ -35,8 +52,6 @@ CORS_ORIGINS=http://localhost:3000 ENABLE_FEATURE_X=false ENABLE_FEATURE_Y=true -# Cache Settings -REDIS_HOST=localhost -REDIS_PORT=6379 -REDIS_DB=0 -CACHE_TTL=3600 \ No newline at end of file +# Testing +TEST_PORT=9500 +MOCK_SERVER_PORT=9600 \ No newline at end of file diff --git a/.env.production b/.env.production new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md index 1c6f951..1b59692 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -# Cursor-Template +# Design-to-Deployment with Cursor -A comprehensive template for Git projects that use [Cursor](https://cursor.sh/), the AI-first IDE. This template provides a structured foundation for developing projects with Cursor, including AI-assisted development workflows, maintenance scripts, and best practices. +A comprehensive framework for transforming design files into deployed applications using Cursor AI. This framework provides a structured workflow for importing designs, generating components, integrating them into pages, validating against design specifications, and deploying to various platforms. ## šŸŽÆ Purpose -This template helps you: -- Set up a well-organized project structure for AI-assisted development -- Implement best practices for code quality and maintenance -- Automate common development tasks -- Maintain consistent coding standards -- Track and optimize AI token usage +This framework helps you: +- Automate the conversion of design files (Figma, Sketch) into production-ready code +- Maintain design fidelity throughout the development process +- Generate consistent components based on design tokens +- Validate implementations against design specifications +- Streamline the deployment process to multiple platforms +- Leverage AI for code generation and visual validation ## šŸ“ Project Structure @@ -17,32 +18,51 @@ This template helps you: . ā”œā”€ā”€ .cursor/ # Cursor-specific configurations │ ā”œā”€ā”€ rules/ # Development rules and guidelines -│ ā”œā”€ā”€ metrics/ # AI usage metrics -│ └── logs/ # Operation logs -ā”œā”€ā”€ scripts/ # Maintenance and utility scripts -│ ā”œā”€ā”€ daily/ # Daily maintenance tasks -│ ā”œā”€ā”€ weekly/ # Weekly code quality checks -│ ā”œā”€ā”€ monthly/ # Monthly security audits -│ └── quarterly/ # Quarterly performance analysis -ā”œā”€ā”€ tests/ # Test files -ā”œā”€ā”€ tools/ # Development tools and utilities -ā”œā”€ā”€ .env.example # Environment variables template -ā”œā”€ā”€ .gitignore # Git ignore rules -└── requirements.txt # Python dependencies +│ ā”œā”€ā”€ logs/ # Operation logs +│ ā”œā”€ā”€ temp/ # Temporary files +│ ā”œā”€ā”€ workflows/ # Workflow records and reports +│ └── deployments/ # Deployment records +ā”œā”€ā”€ designs/ # Design files and extracted assets +│ ā”œā”€ā”€ figma/ # Figma design files +│ ā”œā”€ā”€ sketch/ # Sketch design files +│ ā”œā”€ā”€ tokens/ # Design tokens (colors, typography, etc.) +│ ā”œā”€ā”€ components/ # Component specifications +│ └── screens/ # Screen layouts and compositions +ā”œā”€ā”€ src/ # Source code +│ ā”œā”€ā”€ components/ # Generated components +│ ā”œā”€ā”€ pages/ # Integrated pages +│ ā”œā”€ā”€ styles/ # Generated stylesheets +│ └── utils/ # Utility functions +ā”œā”€ā”€ tools/ # Workflow tools +│ ā”œā”€ā”€ design_importer.py # Import designs from Figma/Sketch +│ ā”œā”€ā”€ design_analyzer.py # Analyze design files and extract tokens +│ ā”œā”€ā”€ component_generator.py # Generate components from design tokens +│ ā”œā”€ā”€ integration_generator.py # Integrate components into pages +│ ā”œā”€ā”€ visual_validator.py # Validate implementation against design +│ ā”œā”€ā”€ deployment_prep.py # Prepare for deployment +│ ā”œā”€ā”€ deployment_automation.py # Automate deployment to various platforms +│ └── workflow_orchestrator.py # Orchestrate the entire workflow +ā”œā”€ā”€ validation/ # Validation results +│ └── visual/ # Visual validation reports +ā”œā”€ā”€ build/ # Build output +ā”œā”€ā”€ tests/ # Test files +ā”œā”€ā”€ .env.example # Environment variables template +ā”œā”€ā”€ .gitignore # Git ignore rules +└── requirements.txt # Python dependencies ``` ## šŸš€ Getting Started -1. **Use this template** +1. **Clone the repository** ```bash - git clone https://github.com/yourusername/Cursor-Template.git your-project - cd your-project + git clone https://github.com/yourusername/design-to-deployment.git + cd design-to-deployment ``` 2. **Set up Python environment** ```bash - python -m venv venv - source venv/bin/activate # or `venv\Scripts\activate` on Windows + python -m venv .venv + source .venv/bin/activate # or `.venv\Scripts\activate` on Windows pip install -r requirements.txt ``` @@ -52,62 +72,124 @@ This template helps you: # Edit .env with your API keys and configurations ``` -## šŸ› ļø Maintenance Scripts +4. **Add design files** + - Place Figma exports in `designs/figma/` + - Place Sketch exports in `designs/sketch/` -### Daily Checks -- `scripts/daily/check_dependencies.py`: Monitors package dependencies +5. **Run the workflow** + ```bash + python tools/workflow_orchestrator.py + ``` + +## šŸ› ļø Workflow Tools + +### Design Import +- `tools/design_importer.py`: Imports designs from Figma or Sketch + ```bash + python tools/design_importer.py --source designs/figma --output-dir designs/imported + ``` + +### Design Analysis +- `tools/design_analyzer.py`: Analyzes design files and extracts tokens ```bash - ./scripts/daily/check_dependencies.py + python tools/design_analyzer.py --input-dir designs/imported --output-dir designs/analyzed ``` -### Weekly Checks -- `scripts/weekly/code_quality_check.py`: Analyzes code quality +### Component Generation +- `tools/component_generator.py`: Generates components from design tokens ```bash - ./scripts/weekly/code_quality_check.py + python tools/component_generator.py --input-dir designs/analyzed --output-dir src/components --framework react ``` -### Monthly Checks -- `scripts/monthly/security_audit.py`: Performs security audits +### Integration +- `tools/integration_generator.py`: Integrates components into pages ```bash - ./scripts/monthly/security_audit.py + python tools/integration_generator.py --components-dir src/components --screens-dir designs/analyzed/screens --output-dir src/pages ``` -### Quarterly Checks -- `scripts/quarterly/performance_analysis.py`: Analyzes system performance +### Visual Validation +- `tools/visual_validator.py`: Validates implementation against design ```bash - ./scripts/quarterly/performance_analysis.py + python tools/visual_validator.py --design-dir designs/imported --implementation-url http://localhost:3000 --output-dir validation/visual ``` -## šŸ“‹ Development Guidelines - -### Test-Driven Development -This template follows TDD practices: -1. Write tests first -2. Implement minimal code to pass tests -3. Refactor while maintaining test coverage - -### Code Quality Standards -- Maintain test coverage above 80% -- Follow PEP 8 style guidelines -- Document all public APIs -- Use type hints - -### AI-Assisted Development -- Utilize Cursor's AI capabilities for: - - Code generation - - Refactoring - - Documentation - - Testing -- Track token usage and costs -- Follow AI-specific best practices - -## šŸ” Quality Gates - -- All tests must pass -- Code coverage >= 80% -- No security vulnerabilities -- All dependencies up to date -- Documentation complete +### Deployment Preparation +- `tools/deployment_prep.py`: Prepares for deployment + ```bash + python tools/deployment_prep.py --env production --build-dir build + ``` + +### Deployment Automation +- `tools/deployment_automation.py`: Automates deployment to various platforms + ```bash + python tools/deployment_automation.py --target vercel --env production --build-dir build + ``` + +### Workflow Orchestration +- `tools/workflow_orchestrator.py`: Orchestrates the entire workflow + ```bash + python tools/workflow_orchestrator.py --config workflow_config.json + ``` + +## šŸ“‹ Workflow Configuration + +The workflow can be configured using a JSON file: + +```json +{ + "workflow": { + "name": "Design to Deployment", + "description": "Transform design files into deployed applications", + "version": "1.0.0" + }, + "steps": [ + { + "name": "design_import", + "tool": "design_importer.py", + "enabled": true, + "params": { + "source": "designs/figma", + "output_dir": "designs/imported" + } + }, + // Additional steps... + ], + "settings": { + "continue_on_error": false, + "parallel_execution": false, + "notification_email": "user@example.com", + "save_artifacts": true + } +} +``` + +## šŸ” Supported Frameworks + +The component generator supports multiple frontend frameworks: + +- React (default) +- Vue.js +- Angular +- Svelte + +Example: +```bash +python tools/component_generator.py --framework vue +``` + +## 🚢 Deployment Targets + +The deployment automation supports multiple targets: + +- Vercel (default) +- Netlify +- AWS +- Custom servers + +Example: +```bash +python tools/deployment_automation.py --target netlify +``` ## šŸ¤ Contributing @@ -135,10 +217,12 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file - [Cursor](https://cursor.sh/) - The AI-first IDE - OpenAI - For GPT models - Anthropic - For Claude models -- Contributors to the maintenance scripts and tools +- Figma and Sketch - For design tools integration ## šŸ”— Useful Links - [Cursor Documentation](https://cursor.sh/docs) -- [Python Best Practices](https://docs.python-guide.org/) -- [Test-Driven Development Guide](https://www.agilealliance.org/glossary/tdd/) \ No newline at end of file +- [Figma API Documentation](https://www.figma.com/developers/api) +- [Sketch API Documentation](https://developer.sketch.com/reference/api/) +- [Vercel Documentation](https://vercel.com/docs) +- [Netlify Documentation](https://docs.netlify.com/) \ No newline at end of file diff --git a/docs/port_standardization.md b/docs/port_standardization.md new file mode 100644 index 0000000..98d5125 --- /dev/null +++ b/docs/port_standardization.md @@ -0,0 +1,135 @@ +# Port Standardization Guide + +## Introduction + +This guide outlines our standardized approach to port allocation for development environments. Consistent port usage across projects helps prevent conflicts, simplifies configuration, and improves developer experience. + +## Why Standardize Ports? + +- **Avoid Conflicts**: Prevent port collisions between different services +- **Simplify Configuration**: Reduce time spent configuring ports for each project +- **Improve Onboarding**: New team members can quickly understand and remember port assignments +- **Enhance Documentation**: Standardized ports make documentation more consistent +- **Streamline Debugging**: Easier to identify which service is running on which port + +## Port Allocation Table + +| Service Type | Application | Standard Port | Notes | +|--------------|-------------|---------------|-------| +| **Frontend** | React/Next.js | 3000 | Default Create React App port | +| | Vue.js | 3100 | | +| | Angular | 3200 | | +| | Static Site Generators | 3300 | Gatsby, Hugo, etc. | +| | Documentation Sites | 3400 | Storybook, Docusaurus, etc. | +| **Backend** | Primary API Server | 8000 | Django, Express, FastAPI, etc. | +| | Secondary API Server | 8001 | For microservices architecture | +| | GraphQL Server | 8080 | | +| | WebSocket Server | 8090 | | +| | Authentication Service | 8100 | | +| | File Upload Service | 8200 | | +| **Databases** | PostgreSQL | 5432 | Default PostgreSQL port | +| | MySQL/MariaDB | 3306 | Default MySQL port | +| | MongoDB | 27017 | Default MongoDB port | +| | Redis | 6379 | Default Redis port | +| | Elasticsearch | 9200 | Default Elasticsearch HTTP port | +| **DevOps** | Nginx/Reverse Proxy | 80, 443 | HTTP and HTTPS | +| | Adminer/Database UI | 8800 | | +| | Monitoring Tools | 9000 | Prometheus, Grafana, etc. | +| | CI/CD Services | 9100 | Jenkins, GitLab Runner, etc. | +| | Docker Registry | 5000 | | +| **Testing** | Test Runners | 9500 | Jest, Mocha, etc. | +| | Mock Servers | 9600 | | +| | Storybook | 6006 | Default Storybook port | +| | Cypress Dashboard | 9700 | | + +## Implementation Guidelines + +### Environment Variables + +Always use environment variables for port configuration: + +```dotenv +# Frontend +FRONTEND_PORT=3000 + +# Backend +API_PORT=8000 +WEBSOCKET_PORT=8090 + +# Databases +DB_PORT=5432 +REDIS_PORT=6379 +``` + +### Docker Compose + +When using Docker Compose, follow this pattern: + +```yaml +services: + frontend: + ports: + - "${FRONTEND_PORT:-3000}:3000" + + backend: + ports: + - "${API_PORT:-8000}:8000" + + database: + ports: + - "${DB_PORT:-5432}:5432" +``` + +### Application Configuration + +In your application code, always read port values from environment variables: + +```javascript +// Node.js example +const port = process.env.API_PORT || 8000; +app.listen(port, () => { + console.log(`Server running on port ${port}`); +}); +``` + +```python +# Python example +import os +port = int(os.getenv('API_PORT', 8000)) +app.run(host='0.0.0.0', port=port) +``` + +## Port Conflict Resolution + +If a port conflict occurs: + +1. Run the port checker utility: `./tools/port_checker.sh` +2. Identify which service is using the conflicting port +3. Either: + - Stop the conflicting service + - Increment your port number by 1 (e.g., 3000 → 3001) + - Configure your application to use a different port +4. Document any non-standard port usage in your project README + +## Best Practices + +1. **Document Port Usage**: Always include port information in your project README +2. **Use Environment Variables**: Never hardcode port numbers +3. **Check Port Availability**: Run the port checker before starting development +4. **Handle Port Binding Failures**: Implement proper error handling in your application +5. **Use Port Ranges**: For services that need multiple ports, use a consistent range +6. **Local Development Only**: These standards are for development environments only +7. **Production Environments**: In production, use standard ports (80/443) with proper routing + +## Tools + +We provide a port checker utility to help verify port availability: + +```bash +# Check if common development ports are available +./tools/port_checker.sh +``` + +## Conclusion + +Following these port standardization guidelines will help maintain consistency across projects and improve the development experience for all team members. If you have suggestions for improvements to this standard, please submit a pull request with your proposed changes. \ No newline at end of file diff --git a/tools/port_checker.sh b/tools/port_checker.sh new file mode 100755 index 0000000..055c8be --- /dev/null +++ b/tools/port_checker.sh @@ -0,0 +1,51 @@ +#!/bin/bash + +# Port Checker Utility +# This script checks if commonly used development ports are available +# Documentation: .cursor/rules/tools/port-checker.mdc + +echo "Checking port availability for development..." + +# Define port categories +FRONTEND_PORTS=(3000 3100 3200 3300 3400) +BACKEND_PORTS=(8000 8001 8080 8090 8100 8200) +DATABASE_PORTS=(5432 3306 27017 6379 9200) + +# Function to check if a port is in use +check_port() { + nc -z localhost $1 &>/dev/null + if [ $? -eq 0 ]; then + echo "āŒ Port $1 is in use" + return 1 + else + echo "āœ… Port $1 is available" + return 0 + fi +} + +# Check frontend ports +echo -e "\nšŸ“± Frontend Ports:" +for port in "${FRONTEND_PORTS[@]}"; do + check_port $port +done + +# Check backend ports +echo -e "\nāš™ļø Backend Ports:" +for port in "${BACKEND_PORTS[@]}"; do + check_port $port +done + +# Check database ports +echo -e "\nšŸ’¾ Database Ports:" +for port in "${DATABASE_PORTS[@]}"; do + check_port $port +done + +# Summary +echo -e "\nšŸ“Š Summary:" +echo "If any required ports are in use, you can:" +echo "1. Stop the service using that port" +echo "2. Configure your application to use a different port" +echo "3. Document the port change in your project README" + +echo -e "\nRefer to .cursor/rules/port-standardization.mdc for port allocation guidelines." \ No newline at end of file diff --git a/workflow_config.json b/workflow_config.json new file mode 100644 index 0000000..83f13cd --- /dev/null +++ b/workflow_config.json @@ -0,0 +1,82 @@ +{ + "workflow": { + "name": "Design to Deployment", + "description": "Transform design files into deployed applications", + "version": "1.0.0" + }, + "steps": [ + { + "name": "design_import", + "tool": "design_importer.py", + "enabled": true, + "params": { + "source": "designs/figma", + "output_dir": "designs/imported" + } + }, + { + "name": "design_analysis", + "tool": "design_analyzer.py", + "enabled": true, + "params": { + "input_dir": "designs/imported", + "output_dir": "designs/analyzed" + } + }, + { + "name": "component_generation", + "tool": "component_generator.py", + "enabled": true, + "params": { + "input_dir": "designs/analyzed", + "output_dir": "src/components", + "framework": "react" + } + }, + { + "name": "integration", + "tool": "integration_generator.py", + "enabled": true, + "params": { + "components_dir": "src/components", + "screens_dir": "designs/analyzed/screens", + "output_dir": "src/pages" + } + }, + { + "name": "visual_validation", + "tool": "visual_validator.py", + "enabled": true, + "params": { + "design_dir": "designs/imported", + "implementation_url": "http://localhost:3000", + "output_dir": "validation/visual" + } + }, + { + "name": "deployment_preparation", + "tool": "deployment_prep.py", + "enabled": true, + "params": { + "env": "production", + "build_dir": "build" + } + }, + { + "name": "deployment", + "tool": "deployment_automation.py", + "enabled": true, + "params": { + "target": "vercel", + "env": "production", + "build_dir": "build" + } + } + ], + "settings": { + "continue_on_error": false, + "parallel_execution": false, + "notification_email": "user@example.com", + "save_artifacts": true + } +} \ No newline at end of file