v4.0.0-beta.435

.AI_INSTRUCTIONS_SYNC.md

@@ -0,0 +1,156 @@
+# AI Instructions Synchronization Guide
+
+This document explains how AI instructions are organized and synchronized across different AI tools used with Coolify.
+
+## Overview
+
+Coolify maintains AI instructions in two parallel systems:
+
+1. **CLAUDE.md** - For Claude Code (claude.ai/code)
+2. **.cursor/rules/** - For Cursor IDE and other AI assistants
+
+Both systems share core principles but are optimized for their respective workflows.
+
+## Structure
+
+### CLAUDE.md
+- **Purpose**: Condensed, workflow-focused guide for Claude Code
+- **Format**: Single markdown file
+- **Includes**:
+  - Quick-reference development commands
+  - High-level architecture overview
+  - Core patterns and guidelines
+  - Embedded Laravel Boost guidelines
+  - References to detailed .cursor/rules/ documentation
+
+### .cursor/rules/
+- **Purpose**: Detailed, topic-specific documentation
+- **Format**: Multiple .mdc files organized by topic
+- **Structure**:
+  - `README.mdc` - Main index and overview
+  - `cursor_rules.mdc` - Maintenance guidelines
+  - Topic-specific files (testing-patterns.mdc, security-patterns.mdc, etc.)
+- **Used by**: Cursor IDE, Claude Code (for detailed reference), other AI assistants
+
+## Cross-References
+
+Both systems reference each other:
+
+- **CLAUDE.md** → references `.cursor/rules/` for detailed documentation
+- **.cursor/rules/README.mdc** → references `CLAUDE.md` for Claude Code workflow
+- **.cursor/rules/cursor_rules.mdc** → notes that changes should sync with CLAUDE.md
+
+## Maintaining Consistency
+
+When updating AI instructions, follow these guidelines:
+
+### 1. Core Principles (MUST be consistent)
+- Laravel version (currently Laravel 12)
+- PHP version (8.4)
+- Testing execution rules (Docker for Feature tests, mocking for Unit tests)
+- Security patterns and authorization requirements
+- Code style requirements (Pint, PSR-12)
+
+### 2. Where to Make Changes
+
+**For workflow changes** (how to run commands, development setup):
+- Primary: `CLAUDE.md`
+- Secondary: `.cursor/rules/development-workflow.mdc`
+
+**For architectural patterns** (how code should be structured):
+- Primary: `.cursor/rules/` topic files
+- Secondary: Reference in `CLAUDE.md` "Additional Documentation" section
+
+**For testing patterns**:
+- Both: Must be synchronized
+- `CLAUDE.md` - Contains condensed testing execution rules
+- `.cursor/rules/testing-patterns.mdc` - Contains detailed examples and patterns
+
+### 3. Update Checklist
+
+When making significant changes:
+
+- [ ] Identify if change affects core principles (version numbers, critical patterns)
+- [ ] Update primary location (CLAUDE.md or .cursor/rules/)
+- [ ] Check if update affects cross-referenced content
+- [ ] Update secondary location if needed
+- [ ] Verify cross-references are still accurate
+- [ ] Run: `./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc` (if applicable)
+
+### 4. Common Inconsistencies to Watch
+
+- **Version numbers**: Laravel, PHP, package versions
+- **Testing instructions**: Docker execution requirements
+- **File paths**: Ensure relative paths work from root
+- **Command syntax**: Docker commands, artisan commands
+- **Architecture decisions**: Laravel 10 structure vs Laravel 12+ structure
+
+## File Organization
+
+```
+/
+├── CLAUDE.md                          # Claude Code instructions (condensed)
+├── .AI_INSTRUCTIONS_SYNC.md          # This file
+└── .cursor/
+    └── rules/
+        ├── README.mdc                 # Index and overview
+        ├── cursor_rules.mdc           # Maintenance guide
+        ├── testing-patterns.mdc       # Testing details
+        ├── development-workflow.mdc   # Dev setup details
+        ├── security-patterns.mdc      # Security details
+        ├── application-architecture.mdc
+        ├── deployment-architecture.mdc
+        ├── database-patterns.mdc
+        ├── frontend-patterns.mdc
+        ├── api-and-routing.mdc
+        ├── form-components.mdc
+        ├── technology-stack.mdc
+        ├── project-overview.mdc
+        └── laravel-boost.mdc          # Laravel-specific patterns
+```
+
+## Recent Updates
+
+### 2025-10-07
+- ✅ Added cross-references between CLAUDE.md and .cursor/rules/
+- ✅ Synchronized Laravel version (12) across all files
+- ✅ Added comprehensive testing execution rules (Docker for Feature tests)
+- ✅ Added test design philosophy (prefer mocking over database)
+- ✅ Fixed inconsistencies in testing documentation
+- ✅ Created this synchronization guide
+
+## Maintenance Commands
+
+```bash
+# Check for version inconsistencies
+grep -r "Laravel [0-9]" CLAUDE.md .cursor/rules/*.mdc
+
+# Check for PHP version consistency
+grep -r "PHP [0-9]" CLAUDE.md .cursor/rules/*.mdc
+
+# Format all documentation
+./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc
+
+# Search for specific patterns across all docs
+grep -r "pattern_to_check" CLAUDE.md .cursor/rules/
+```
+
+## Contributing
+
+When contributing documentation:
+
+1. Check both CLAUDE.md and .cursor/rules/ for existing documentation
+2. Add to appropriate location(s) based on guidelines above
+3. Add cross-references if creating new patterns
+4. Update this file if changing organizational structure
+5. Verify consistency before submitting PR
+
+## Questions?
+
+If unsure about where to document something:
+
+- **Quick reference / workflow** → CLAUDE.md
+- **Detailed patterns / examples** → .cursor/rules/[topic].mdc
+- **Both?** → Start with .cursor/rules/, then reference in CLAUDE.md
+
+When in doubt, prefer detailed documentation in .cursor/rules/ and concise references in CLAUDE.md.

.cursor/rules/README.mdc

@@ -9,6 +9,10 @@ alwaysApply: false
 
 This comprehensive set of Cursor Rules provides deep insights into **Coolify**, an open-source self-hostable alternative to Heroku/Netlify/Vercel. These rules will help you understand, navigate, and contribute to this complex Laravel-based deployment platform.
 
+> **Cross-Reference**: This directory is for **detailed, topic-specific rules** used by Cursor IDE and other AI assistants. For Claude Code specifically, also see **[CLAUDE.md](mdc:CLAUDE.md)** which provides a condensed, workflow-focused guide. Both systems share core principles but are optimized for their respective tools.
+>
+> **Maintaining Rules**: When updating these rules, see **[.AI_INSTRUCTIONS_SYNC.md](mdc:.AI_INSTRUCTIONS_SYNC.md)** for synchronization guidelines to keep CLAUDE.md and .cursor/rules/ consistent.
+
 ## Rule Categories
 
 ### 🏗️ Architecture & Foundation
@@ -71,7 +75,7 @@ Coolify uses a **team-based multi-tenancy** model where:
 - **Multi-server** support with SSH connections
 
 ### 3. Technology Stack
-- **Backend**: Laravel 11 + PHP 8.4
+- **Backend**: Laravel 12 + PHP 8.4
 - **Frontend**: Livewire 3.5 + Alpine.js + Tailwind CSS 4.1
 - **Database**: PostgreSQL 15 + Redis 7
 - **Containerization**: Docker + Docker Compose

.cursor/rules/cursor_rules.mdc

@@ -4,6 +4,12 @@ globs: .cursor/rules/*.mdc
 alwaysApply: true
 ---
 
+# Cursor Rules Maintenance Guide
+
+> **Important**: These rules in `.cursor/rules/` are shared between Cursor IDE and other AI assistants. Changes here should be reflected in **[CLAUDE.md](mdc:CLAUDE.md)** when they affect core workflows or patterns.
+>
+> **Synchronization Guide**: See **[.AI_INSTRUCTIONS_SYNC.md](mdc:.AI_INSTRUCTIONS_SYNC.md)** for detailed guidelines on maintaining consistency between CLAUDE.md and .cursor/rules/.
+
 - **Required Rule Structure:**
   ```markdown
   ---

.cursor/rules/database-patterns.mdc

@@ -142,6 +142,29 @@ Schema::create('applications', function (Blueprint $table) {
 - **Soft deletes** for audit trails
 - **Activity logging** with Spatie package
 
+### **CRITICAL: Mass Assignment Protection**
+**When adding new database columns, you MUST update the model's `$fillable` array.** Without this, Laravel will silently ignore mass assignment operations like `Model::create()` or `$model->update()`.
+
+**Checklist for new columns:**
+1. ✅ Create migration file
+2. ✅ Run migration
+3. ✅ **Add column to model's `$fillable` array**
+4. ✅ Update any Livewire components that sync this property
+5. ✅ Test that the column can be read and written
+
+**Example:**
+```php
+class Server extends BaseModel
+{
+    protected $fillable = [
+        'name',
+        'ip',
+        'port',
+        'is_validating', // ← MUST add new columns here
+    ];
+}
+```
+
 ### Relationship Patterns
 ```php
 // Typical relationship structure in Application model

.cursor/rules/laravel-boost.mdc

@@ -185,7 +185,7 @@ protected function isAccessible(User $user, ?string $path = null): bool
 
 ### Database
 - When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
-- Laravel 11 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
+- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
 
 ### Models
 - Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.

.cursor/rules/testing-patterns.mdc

@@ -5,11 +5,56 @@ alwaysApply: false
 ---
 # Coolify Testing Architecture & Patterns
 
+> **Cross-Reference**: These detailed testing patterns align with the testing guidelines in **[CLAUDE.md](mdc:CLAUDE.md)**. Both documents share the same core principles about Docker execution and mocking preferences.
+
 ## Testing Philosophy
 
 Coolify employs **comprehensive testing strategies** using modern PHP testing frameworks to ensure reliability of deployment operations, infrastructure management, and user interactions.
 
-!Important: Always run tests inside `coolify` container.
+### Test Execution Rules
+
+**CRITICAL**: Tests are categorized by database dependency:
+
+#### Unit Tests (`tests/Unit/`)
+- **MUST NOT** use database connections
+- **MUST** use mocking for models and external dependencies
+- **CAN** run outside Docker: `./vendor/bin/pest tests/Unit`
+- Purpose: Test isolated logic, helper functions, and business rules
+
+#### Feature Tests (`tests/Feature/`)
+- **MAY** use database connections (factories, migrations, models)
+- **MUST** run inside Docker container: `docker exec coolify php artisan test`
+- **MUST** use `RefreshDatabase` trait if touching database
+- Purpose: Test API endpoints, workflows, and integration scenarios
+
+**Rule of thumb**: If your test needs `Server::factory()->create()` or any database operation, it's a Feature test and MUST run in Docker.
+
+### Prefer Mocking Over Database
+
+When writing tests, always prefer mocking over real database operations:
+
+```php
+// ❌ BAD: Unit test using database
+it('extracts custom commands', function () {
+    $server = Server::factory()->create(['ip' => '1.2.3.4']);
+    $commands = extract_custom_proxy_commands($server, $yaml);
+    expect($commands)->toBeArray();
+});
+
+// ✅ GOOD: Unit test using mocking
+it('extracts custom commands', function () {
+    $server = Mockery::mock('App\Models\Server');
+    $server->shouldReceive('proxyType')->andReturn('traefik');
+    $commands = extract_custom_proxy_commands($server, $yaml);
+    expect($commands)->toBeArray();
+});
+```
+
+**Design principles for testable code:**
+- Use dependency injection instead of global state
+- Create interfaces for external dependencies (SSH, Docker, etc.)
+- Separate business logic from data persistence
+- Make functions accept interfaces instead of concrete models when possible
 
 ## Testing Framework Stack
 

.github/workflows/claude-code-review.yml

@@ -34,25 +34,46 @@ jobs:
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@beta
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          prompt: |
-            REPO: ${{ github.repository }}
-            PR NUMBER: ${{ github.event.pull_request.number }}
 
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1)
+          # model: "claude-opus-4-1-20250805"
+
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_prompt: |
             Please review this pull request and provide feedback on:
             - Code quality and best practices
             - Potential bugs or issues
             - Performance considerations
             - Security concerns
             - Test coverage
 
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+            Be constructive and helpful in your feedback.
 
-            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          # use_sticky_comment: true
+
+          # Optional: Customize review based on file types
+          # direct_prompt: |
+          #   Review this PR focusing on:
+          #   - For TypeScript files: Type safety and proper interface usage
+          #   - For API endpoints: Security, input validation, and error handling
+          #   - For React components: Performance, accessibility, and best practices
+          #   - For tests: Coverage, edge cases, and test quality
+
+          # Optional: Different prompts for different authors
+          # direct_prompt: |
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' && 
+          #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
+          #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
+
+          # Optional: Add specific tools for running tests or linting
+          # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
 
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+          # Optional: Skip review for certain conditions
+          # if: |
+          #   !contains(github.event.pull_request.title, '[skip-review]') &&
+          #   !contains(github.event.pull_request.title, '[WIP]')
 

.github/workflows/claude.yml

@@ -16,6 +16,8 @@ jobs:
       (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && github.event.action == 'labeled' && github.event.label.name == 'Claude') ||
+      (github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'Claude') ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
     runs-on: ubuntu-latest
     permissions:
@@ -34,22 +36,30 @@ jobs:
         id: claude
         uses: anthropics/claude-code-action@v1
         with:
-       - name: Run Claude Code
-         id: claude
-         uses: anthropics/claude-code-action@v1
-         with:
-           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-           # This is an optional setting that allows Claude to read CI results on PRs
-           additional_permissions: |
-             actions: read
+          anthropic_api_key: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
-
-          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
-          # prompt: 'Update the pull request description to include a summary of changes.'
-
-          # Optional: Add claude_args to customize behavior and configuration
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
-
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1)
+          # model: "claude-opus-4-1-20250805"
+
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test