csarigoz · csarigoz · May 29, 2025 · May 29, 2025 · May 29, 2025 · May 29, 2025
diff --git a/.cursor/rules/project-rules.mdc b/.cursor/rules/project-rules.mdc
@@ -3,4 +3,4 @@ description:
 globs: 
 alwaysApply: true
 ---
-Follow the rules in the [PROJECT_RULES.md](mdc:PROJECT_RULES.md) (/PROJECT_RULES.md) file at all times, and keep it up to date.
+Follow the rules in the [PROJECT_RULES.md](mdc:PROJECT_RULES.md) (PROJECT_RULES.md) file at all times, and keep it up to date.
diff --git a/.env.example b/.env.example
@@ -1,13 +1,68 @@
-AWS_ACCESS_KEY=YOUR_AWS_ACCESS_KEY
-AWS_SECRET_KEY=YOUR_AWS_SECRET_KEY
-S3_BUCKET=YOUR_S3_BUCKET
-CLOUDFRONT_DOMAIN=YOUR_CLOUDFRONT_DOMAIN
+# Image Upload Utility Configuration
+# Copy this file to .env and update with your actual credentials
 
-# AltText.ai API Configuration
-ALTTEXT_AI_API_KEY=YOUR_ALTTEXT_AI_API_KEY
+# ===============================================
+# Provider Selection
+# ===============================================
+# Choose your upload provider: 'cloudfront' or 'cloudinary'
+UPLOAD_PROVIDER=cloudinary
 
-# Optional: Custom keywords for SEO optimization
-ALTTEXT_AI_KEYWORDS=YOUR_ALTTEXT_AI_KEYWORDS
+# ===============================================
+# Cloudinary Configuration (Recommended)
+# ===============================================
+# Sign up at https://cloudinary.com to get these credentials
+# Found in your Cloudinary Dashboard > Settings > API Keys
+
+CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
+CLOUDINARY_API_KEY=your_cloudinary_api_key
+CLOUDINARY_API_SECRET=your_cloudinary_api_secret
+
+# ===============================================
+# AWS CloudFront/S3 Configuration (Alternative)
+# ===============================================
+# Required for CloudFront provider
+# Get these from AWS IAM > Users > Security credentials
+
+AWS_ACCESS_KEY=your_aws_access_key_here
+AWS_SECRET_KEY=your_aws_secret_key_here
+S3_BUCKET=your-s3-bucket-name
+CLOUDFRONT_DOMAIN=your-cloudfront-domain.cloudfront.net
+
+# ===============================================
+# AltText.ai Configuration (Optional)
+# ===============================================
+# AI-powered alt text generation for accessibility and SEO
+# Sign up at https://alttext.ai to get API key
+
+ALTTEXT_AI_API_KEY=your_alttext_ai_api_key_here
+
+# Optional: Default keywords for SEO optimization
+ALTTEXT_AI_KEYWORDS=product,modern,lifestyle
 
 # Optional: Webhook URL for asynchronous processing
-ALTTEXT_AI_WEBHOOK_URL=YOUR_ALTTEXT_AI_WEBHOOK_URL
+ALTTEXT_AI_WEBHOOK_URL=https://your-domain.com/webhook
+
+# ===============================================
+# Quick Setup Guide
+# ===============================================
+#
+# For Cloudinary (Recommended):
+# 1. Sign up at https://cloudinary.com
+# 2. Go to Dashboard > Settings > Access Keys
+# 3. Copy Cloud name, API Key, and API Secret above
+# 4. Set UPLOAD_PROVIDER=cloudinary
+# 5. Run: python setup.py
+#
+# For AWS CloudFront:
+# 1. Create S3 bucket with public read access
+# 2. Create CloudFront distribution pointing to S3
+# 3. Create IAM user with S3 permissions
+# 4. Copy credentials above
+# 5. Set UPLOAD_PROVIDER=cloudfront
+# 6. Run: python setup.py
+#
+# For AltText.ai (Optional):
+# 1. Sign up at https://alttext.ai
+# 2. Get API key from dashboard
+# 3. Add ALTTEXT_AI_API_KEY above
+# 4. Run: python setup.py 
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -21,17 +21,29 @@ Brief description of the changes in this PR.
 - [ ] ⚡ Performance improvements
 - [ ] 🧪 Adding or updating tests
 - [ ] 🔧 Build/CI changes
+- [ ] 🌐 Provider-specific changes (Cloudinary/CloudFront)
 
 ## 🚀 Changes Made
 
 ### Core Changes
-- [ ] Modified `upload_files.py`
-- [ ] Modified `alttext_ai.py`
-- [ ] Modified `setup.py`
-- [ ] Modified `process_csv.sh`
+- [ ] Modified `upload_files.py` (legacy CloudFront application)
+- [ ] Modified `unified_upload.py` (new multi-provider system)
+- [ ] Modified `cloudinary_provider.py` (Cloudinary integration)
+- [ ] Modified `cloudfront_provider.py` (CloudFront provider)
+- [ ] Modified `upload_provider.py` (provider factory/interface)
+- [ ] Modified `alttext_ai.py` (AltText.ai integration)
+- [ ] Modified `setup.py` (environment setup)
+- [ ] Modified `process_csv.sh` (interactive processor)
 - [ ] Added new files
 - [ ] Updated dependencies
 
+### Provider-Specific Changes
+- [ ] Cloudinary transformations/optimizations
+- [ ] CloudFront/S3 upload logic
+- [ ] Provider auto-detection logic
+- [ ] Provider factory pattern
+- [ ] Multi-provider configuration
+
 ### Specific Changes
 - List specific changes made
 - Include any new functions/classes added
@@ -40,26 +52,47 @@ Brief description of the changes in this PR.
 
 ## 🧪 Testing
 
+### Multi-Provider Testing
+- [ ] Tested with Cloudinary provider
+- [ ] Tested with CloudFront provider
+- [ ] Tested provider auto-detection
+- [ ] Tested provider switching
+- [ ] Tested with both providers configured
+
 ### Manual Testing Performed
 - [ ] Tested image upload functionality
 - [ ] Tested CSV processing
+- [ ] Tested local file uploads
 - [ ] Tested AltText.ai integration
-- [ ] Tested Flask API endpoints
+- [ ] Tested Flask API endpoints (legacy)
+- [ ] Tested unified command line interface
 - [ ] Tested error handling scenarios
+- [ ] Tested provider connection validation
 
 ### Test Cases Covered
 ```bash
-# Commands used for testing
-python upload_files.py
+# Multi-provider testing commands
+python test_cloudinary.py
+python unified_upload.py --provider cloudinary --mode csv
+python unified_upload.py --provider cloudfront --mode csv
+python unified_upload.py --mode stats  # Auto-detection
 ./process_csv.sh
-python alttext_ai.py
+
+# Legacy testing commands  
+python upload_files.py
+
+# Provider-specific testing
+python cloudinary_provider.py
+python cloudfront_provider.py
 ```
 
 ### Test Results
 - [ ] All existing functionality works as expected
 - [ ] New functionality works as described
 - [ ] Error cases are handled gracefully
 - [ ] Performance is acceptable
+- [ ] Both providers work correctly
+- [ ] Provider switching works seamlessly
 
 ## 📸 Screenshots (if applicable)
 
@@ -73,9 +106,19 @@ After:
 
 ### Environment Variables
 ```bash
-# New or modified environment variables
-NEW_VARIABLE=example_value
-MODIFIED_VARIABLE=new_default_value
+# Multi-provider configuration
+UPLOAD_PROVIDER=cloudinary  # or 'cloudfront' or 'auto'
+
+# Cloudinary configuration
+CLOUDINARY_CLOUD_NAME=your_cloud_name
+CLOUDINARY_API_KEY=your_api_key
+CLOUDINARY_API_SECRET=your_api_secret
+
+# CloudFront configuration (existing)
+AWS_ACCESS_KEY=your_aws_access_key
+AWS_SECRET_KEY=your_aws_secret_key
+S3_BUCKET=your_s3_bucket_name
+CLOUDFRONT_DOMAIN=your_cloudfront_domain
 ```
 
 ### Dependencies
@@ -93,9 +136,27 @@ MODIFIED_VARIABLE=new_default_value
 - [ ] Updated README.md
 - [ ] Updated CONTRIBUTING.md
 - [ ] Updated PROJECT_RULES.md
+- [ ] Updated CHANGELOG.md
 - [ ] Added inline code comments
 - [ ] Updated function docstrings
 - [ ] Added usage examples
+- [ ] Updated provider comparison documentation
+
+## ✅ Pre-Commit Validation
+
+**MANDATORY: All PRs must pass pre-commit checks**
+
+- [ ] Ran `./pre_commit_check.sh` and all checks pass
+- [ ] Code formatting (black, isort) applied
+- [ ] Linting (flake8) passes
+- [ ] Security checks (bandit, safety) pass
+- [ ] All imports and functionality validated
+- [ ] No uncommitted changes remain
+
+```bash
+# Verification command
+./pre_commit_check.sh
+```
 
 ## ✅ Checklist
 
@@ -105,22 +166,26 @@ MODIFIED_VARIABLE=new_default_value
 - [ ] I have commented my code, particularly in hard-to-understand areas
 - [ ] My changes generate no new warnings
 - [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have followed the Git workflow (feature branch, no direct commits to main)
 
 ### Documentation
 - [ ] I have made corresponding changes to the documentation
 - [ ] I have updated the PROJECT_RULES.md if needed
 - [ ] I have added examples for new features
+- [ ] Provider-specific documentation is updated
 
 ### Testing
 - [ ] I have tested my changes locally
-- [ ] I have tested with different Python versions (if applicable)
+- [ ] I have tested with different Python versions (3.9-3.13)
 - [ ] I have tested with different image formats
 - [ ] I have tested error scenarios
+- [ ] I have tested provider-specific functionality
 
 ### Compatibility
-- [ ] My changes are compatible with Python 3.7+
+- [ ] My changes are compatible with Python 3.9+
 - [ ] My changes work on different operating systems
 - [ ] My changes don't break existing functionality
+- [ ] Backward compatibility is maintained for CloudFront users
 
 ## 🔍 Review Focus Areas
 
@@ -130,12 +195,17 @@ Please pay special attention to:
 - [ ] Error handling
 - [ ] Code maintainability
 - [ ] Documentation clarity
+- [ ] Provider abstraction correctness
+- [ ] Backward compatibility
+- [ ] Multi-provider configuration handling
 
 ## 🤝 Contribution Guidelines
 
 - [ ] I have read and followed the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines
 - [ ] I have followed the [PROJECT_RULES.md](../PROJECT_RULES.md) conventions
 - [ ] I understand this contribution will be licensed under the MIT License
+- [ ] I have not committed directly to the main branch
+- [ ] I am using a descriptive branch name with appropriate prefix
 
 ## 📝 Additional Notes
 
@@ -148,6 +218,9 @@ Please pay special attention to:
 ### Known Limitations
 <!-- List any known limitations or edge cases -->
 
+### Provider-Specific Notes
+<!-- Any provider-specific considerations or limitations -->
+
 ---
 
 **For Maintainers:**
@@ -159,15 +232,20 @@ Please pay special attention to:
 - [ ] No security vulnerabilities introduced
 - [ ] Performance impact is acceptable
 - [ ] Breaking changes are properly documented
+- [ ] Pre-commit checks have been run
+- [ ] Provider abstraction is correct
+- [ ] Multi-provider testing completed
 
 ### Merge Checklist
 - [ ] All CI checks pass
 - [ ] At least one maintainer approval
 - [ ] No conflicts with main branch
 - [ ] Release notes updated (if needed)
+- [ ] Branch follows naming conventions
+- [ ] PR title follows conventional commit format
 
 ---
 
-**Thank you for contributing to the CloudFront Image Upload Utility!** 🎉
+**Thank you for contributing to the Multi-Provider Image Upload Utility!** 🎉
 
 Your contribution helps make this tool better for everyone. If you have any questions about this PR, please don't hesitate to ask. 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -64,15 +64,36 @@ jobs:
       run: |
         python -c "import upload_files; print('✅ upload_files imports successfully')"
         python -c "import alttext_ai; print('✅ alttext_ai imports successfully')"
+        python -c "import unified_upload; print('✅ unified_upload imports successfully')"
+        python -c "import upload_provider; print('✅ upload_provider imports successfully')"
+        python -c "import cloudinary_provider; print('✅ cloudinary_provider imports successfully')"
+        python -c "import cloudfront_provider; print('✅ cloudfront_provider imports successfully')"
 
-    - name: Test basic functionality (without AWS credentials)
+    - name: Test basic functionality (without provider credentials)
       run: |
         python -c "
-        from upload_files import optimize_image, get_best_format
+        from upload_files import optimize_image
         from alttext_ai import AltTextAI
+        from upload_provider import ProviderFactory
         print('✅ Core functions import successfully')
         "
 
+    - name: Test provider factory
+      run: |
+        python -c "
+        from upload_provider import ProviderFactory
+        try:
+            # Test factory without credentials (should fail gracefully)
+            provider = ProviderFactory.create_provider('cloudinary')
+            print('❌ Should have failed without credentials')
+        except (ValueError, ImportError) as e:
+            print('✅ Provider factory handles missing credentials correctly')
+        "
+
+    - name: Test unified upload help
+      run: |
+        python unified_upload.py --help
+
     - name: Upload security reports
       uses: actions/upload-artifact@v4
       if: always()
@@ -204,6 +225,11 @@ jobs:
         # Check core files exist
         required_files=(
           "upload_files.py"
+          "unified_upload.py"
+          "upload_provider.py"
+          "cloudinary_provider.py"
+          "cloudfront_provider.py"
+          "test_cloudinary.py"
           "alttext_ai.py"
           "setup.py"
           "requirements.txt"
@@ -253,6 +279,14 @@ jobs:
 
         # Check .env.example has required variables
         required_vars=(
+          "UPLOAD_PROVIDER"
+          "CLOUDINARY_CLOUD_NAME"
+          "CLOUDINARY_API_KEY"
+          "CLOUDINARY_API_SECRET"
+          "AWS_ACCESS_KEY"
+          "AWS_SECRET_KEY"
+          "S3_BUCKET"
+          "CLOUDFRONT_DOMAIN"
           "ALTTEXT_AI_API_KEY"
           "ALTTEXT_AI_KEYWORDS"
           "ALTTEXT_AI_WEBHOOK_URL"

diff --git a/.github/workflows/welcome.yml b/.github/workflows/welcome.yml
@@ -6,6 +6,11 @@ on:
   pull_request_target:
     types: [opened]
 
+permissions:
+  issues: write
+  pull-requests: write
+  contents: read
+
 jobs:
   welcome:
     runs-on: ubuntu-latest