symfonia-ai-tools 1.0.0

package/templates/packs/laravel/_ai/skills/queued-job/SKILL.md

@@ -0,0 +1,248 @@
+# Skill: Queued Job (Laravel)
+
+## Trigger
+Use when creating asynchronous background processing: jobs, events with listeners, scheduled tasks.
+
+## Input
+- What the job does (e.g. "send export email", "sync external API")
+- Trigger: event / manual dispatch / schedule
+- Input data needed
+- Expected output / side effects
+
+## Steps
+
+### 1. Decide architecture
+
+- **Simple async task** → Job only
+- **Something happened, react to it** → Event + Listener(s)
+- **Recurring task** → Job + Schedule
+- **Multiple reactions to one trigger** → Event + multiple Listeners
+
+### 2. Create Event (if event-driven)
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan make:event [Entity][Action]Event --path=Modules/[Module]/Domain/Events
+```
+
+```php
+declare(strict_types=1);
+
+namespace Modules\[Module]\Domain\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class [Entity][Action]Event
+{
+    use Dispatchable;
+    use SerializesModels;
+
+    public function __construct(
+        public readonly int $entityId,
+        public readonly int $userId,
+        // ... minimal data needed by listeners
+    ) {}
+}
+```
+
+Rules:
+- Pass IDs, not full models (serialization safety)
+- Keep payload minimal — listeners query fresh data
+- Use `readonly` properties
+
+### 3. Create Job
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan make:job [Action][Entity]Job --path=Modules/[Module]/Domain/Jobs
+```
+
+```php
+declare(strict_types=1);
+
+namespace Modules\[Module]\Domain\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class [Action][Entity]Job implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+    public int $backoff = 60; // seconds between retries
+    public int $timeout = 120; // max execution time
+
+    public function __construct(
+        private readonly int $entityId,
+        private readonly int $userId,
+    ) {}
+
+    public function handle([Entity]Service $service): void
+    {
+        // Fetch fresh data
+        $entity = $service->findOrFail($this->entityId);
+
+        // Business logic
+        $service->processAction($entity);
+    }
+
+    public function failed(\Throwable $exception): void
+    {
+        // Log failure, notify admin, update status
+        \Log::error("[Action][Entity]Job failed", [
+            'entity_id' => $this->entityId,
+            'error' => $exception->getMessage(),
+        ]);
+    }
+}
+```
+
+Rules:
+- Always set `$tries`, `$backoff`, `$timeout`
+- Implement `failed()` for error handling
+- Use constructor injection for dependencies in `handle()`
+- Pass IDs in constructor, fetch fresh data in `handle()`
+- Job must be idempotent (safe to retry)
+
+### 4. Create Listener (if event-driven)
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan make:listener [Action]On[Event]Listener --path=Modules/[Module]/Domain/Listeners
+```
+
+```php
+declare(strict_types=1);
+
+namespace Modules\[Module]\Domain\Listeners;
+
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Modules\[Module]\Domain\Events\[Entity][Action]Event;
+
+class [Action]On[Event]Listener implements ShouldQueue
+{
+    public int $tries = 3;
+    public int $backoff = 60;
+
+    public function __construct(
+        private readonly [Entity]Service $service,
+    ) {}
+
+    public function handle([Entity][Action]Event $event): void
+    {
+        $this->service->doAction($event->entityId);
+    }
+
+    public function shouldQueue([Entity][Action]Event $event): bool
+    {
+        // Optional: conditionally skip processing
+        return true;
+    }
+}
+```
+
+### 5. Register Event-Listener mapping
+
+In module's `ServiceProvider`:
+
+```php
+protected $listen = [
+    [Entity][Action]Event::class => [
+        [Action]On[Event]Listener::class,
+    ],
+];
+```
+
+### 6. Dispatch
+
+From service/controller:
+
+```php
+// Direct job dispatch
+[Action][Entity]Job::dispatch($entity->getId(), $user->getId());
+
+// With delay
+[Action][Entity]Job::dispatch($entityId, $userId)
+    ->delay(now()->addMinutes(5));
+
+// Event dispatch
+[Entity][Action]Event::dispatch($entity->getId(), $user->getId());
+
+// On specific queue
+[Action][Entity]Job::dispatch($entityId, $userId)
+    ->onQueue('exports');
+```
+
+### 7. Schedule (if recurring)
+
+In `Console/Kernel.php` or module's ServiceProvider:
+
+```php
+$schedule->job(new [Action][Entity]Job)->dailyAt('03:00');
+```
+
+### 8. Write tests
+
+```php
+// Test job dispatched
+public function test_action_dispatches_job(): void
+{
+    Queue::fake();
+
+    $this->service->triggerAction($this->entity);
+
+    Queue::assertPushed([Action][Entity]Job::class, function ($job) {
+        return $job->entityId === $this->entity->getId();
+    });
+}
+
+// Test job execution
+public function test_job_processes_entity(): void
+{
+    $job = new [Action][Entity]Job($this->entity->getId(), $this->user->getId());
+    $job->handle(app([Entity]Service::class));
+
+    $this->entity->refresh();
+    $this->assertEquals('processed', $this->entity->getStatus()->value);
+}
+
+// Test event triggers listeners
+public function test_event_triggers_listener(): void
+{
+    Event::fake();
+
+    [Entity][Action]Event::dispatch($this->entity->getId(), $this->user->getId());
+
+    Event::assertDispatched([Entity][Action]Event::class);
+}
+
+// Test idempotency
+public function test_job_is_idempotent(): void
+{
+    $job = new [Action][Entity]Job($this->entity->getId(), $this->user->getId());
+    $service = app([Entity]Service::class);
+
+    $job->handle($service);
+    $job->handle($service); // second run should not break
+
+    // Assert expected state (same as single run)
+}
+```
+
+### 9. Verification checklist
+
+- [ ] `declare(strict_types=1)` in all files
+- [ ] Job has `$tries`, `$backoff`, `$timeout`
+- [ ] Job implements `failed()` method
+- [ ] Job is idempotent (safe to retry)
+- [ ] Constructor takes IDs, `handle()` fetches fresh data
+- [ ] Event uses `readonly` properties with minimal payload
+- [ ] Listener registered in ServiceProvider
+- [ ] Tests: dispatch, execution, idempotency
+- [ ] `Queue::fake()` / `Event::fake()` in tests
+- [ ] Error handling logs enough context for debugging

package/templates/packs/laravel/_ai/skills/testing-feature/SKILL.md

@@ -0,0 +1,196 @@
+# Skill: Laravel Feature Tests
+
+## Trigger
+Use when writing feature tests — HTTP controller tests, service integration tests with real database.
+
+## File Location & Namespace
+
+- Controllers: `Modules/{Module}/Tests/Feature/Controllers/{ControllerName}Test.php`
+- Services: `Modules/{Module}/Tests/Feature/Services/{ServiceName}Test.php`
+- Namespace mirrors path: `Modules\{Module}\Tests\Feature\Controllers` / `Services`
+
+## Base Class
+
+Feature tests extend `Tests\TestCase` which provides:
+- `DatabaseTransactions` trait (auto-rollback, no manual cleanup needed)
+- `$this->user` — a factory-created user
+- `$this->companyId` — the user's company ID
+
+**Never** extend `PHPUnit\Framework\TestCase` for feature tests — always use `Tests\TestCase`.
+
+## Controller Test Structure
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{Module}\Tests\Feature\Controllers;
+
+use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
+use Tests\TestCase;
+
+class {Resource}ControllerTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->actingAs($this->user, 'api-passport');
+        $this->withHeader('X-Requested-With', 'XMLHttpRequest');
+    }
+
+    // --- all public test methods first ---
+
+    public function test_index_returns_ok_with_permission(): void
+    {
+        $this->grantPermission();
+
+        $response = $this->getJson('/api/v4/{resource}?page=1&limit=10');
+
+        $response->assertOk();
+    }
+
+    public function test_index_returns_403_without_permission(): void
+    {
+        $response = $this->getJson('/api/v4/{resource}?page=1&limit=10');
+
+        $response->assertForbidden();
+    }
+
+    // --- private helper methods at BOTTOM ---
+
+    private function grantPermission(): void
+    {
+        // Grant module permission to test user
+    }
+}
+```
+
+## Service Test Structure
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{Module}\Tests\Feature\Services;
+
+use Tests\TestCase;
+
+class {ServiceName}Test extends TestCase
+{
+    public function test_store_creates_entity(): void
+    {
+        $result = $this->createService()->store($this->companyId, $data);
+
+        $this->assertDatabaseHas(Entity::TABLE_NAME, [
+            Entity::COLUMN_ID => $result->getId(),
+        ]);
+    }
+
+    private function createService(): {ServiceName}
+    {
+        return app({ServiceName}::class);
+    }
+}
+```
+
+## Required Conventions
+
+### Method naming
+- Prefix: `test_` + `snake_case` description
+- No `@test` annotation
+- All methods must have explicit return type (`: void` for tests)
+
+### Class structure order
+1. Properties (`private`, `protected`)
+2. `setUp()` / `tearDown()`
+3. All `public` test methods
+4. All `private` helper methods — **always at the bottom**
+
+### HTTP status codes
+Always use `Symfony\Component\HttpFoundation\Response as SymfonyResponse` constants or Laravel shortcuts:
+```php
+$response->assertOk();           // 200
+$response->assertForbidden();    // 403
+$response->assertNotFound();     // 404
+$response->assertUnprocessable(); // 422
+$response->assertNoContent();    // 204
+$response->assertStatus(SymfonyResponse::HTTP_CREATED); // 201
+```
+
+### Closure type hints
+```php
+use Mockery\MockInterface;
+$this->mock(Repository::class, function (MockInterface $mock): void { ... });
+```
+
+### Mocking
+Use Laravel fakes for framework services:
+```php
+Event::fake();
+Bus::fake();
+Mail::fake();
+Queue::fake();
+```
+
+## Data Resilience Rules
+
+### Never delete pre-existing data
+`DatabaseTransactions` handles cleanup. Never call `->delete()` or `truncate()` in setUp or tests.
+
+### Before/after delta for counts
+```php
+// Bad — breaks if pre-existing data exists
+$response->assertJsonCount(0, 'data');
+
+// Good — delta pattern
+$beforeTotal = $this->getJson($url)->json('meta.total');
+// ... create 3 items ...
+$afterTotal = $this->getJson($url)->json('meta.total');
+$this->assertSame($beforeTotal + 3, $afterTotal);
+```
+
+### Search by identifier, not position
+```php
+// Bad
+$this->assertSame('Expected', $data[0]['name']);
+
+// Good
+$found = collect($data)->firstWhere('id', $entity->getId());
+$this->assertNotNull($found);
+$this->assertSame('Expected', $found['name']);
+```
+
+### Other company IDs
+Use factory-created companies, never arithmetic:
+```php
+// Bad
+$otherCompanyId = $this->companyId + 999;
+
+// Good
+$otherCompanyId = UserModel::factory()->create()->getCompanyId();
+```
+
+## Controller Test Coverage Checklist
+
+| Scenario | Expected |
+|----------|----------|
+| Happy path with permission | 200 / 201 / 204 |
+| Without permission | 403 |
+| Unauthenticated | 401 |
+| Validation errors | 422 |
+| Resource not found | 404 |
+| Different company access | 403 |
+| Response JSON structure | `assertJsonStructure(...)` |
+
+## Running Tests
+
+```bash
+# Single test class
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter='{TestClassName}'
+
+# Entire module
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter='Modules\\{Module}\\Tests'
+```

package/templates/packs/laravel/_ai/skills/testing-manual/SKILL.md

@@ -0,0 +1,186 @@
+# Skill: Manual HTTP Tests
+
+## Trigger
+Use when creating or modifying API endpoints and manual `.http` test files need to be created or updated.
+
+## Overview
+
+Manual HTTP tests use JetBrains HTTP Client (`.http` files) to test API endpoints directly from PhpStorm/IntelliJ. They complement PHPUnit tests by providing quick, interactive verification of endpoints.
+
+## File Location
+
+- Place `.http` files in `Modules/{Module}/Tests/Manual/`
+- One file per resource is recommended (e.g., `users.http`)
+
+## Authentication
+
+The project uses OAuth 2.0 configured in `http-client.env.json` (copy from `http-client.env.json.example` in project root).
+
+- Use in requests: `Authorization: Bearer {{$auth.token("app")}}`
+- Requests testing unauthorized access must **not** include the `Authorization` header
+
+## Request Naming Convention
+
+Format: `### {Module} - {Action} {Resource} - {Scenario}`
+
+Where:
+- `{Module}` — Laravel module name
+- `{Action}` — HTTP action (Create, Get, List, Count, Update, Delete, Archive, Restore, etc.)
+- `{Resource}` — resource name
+- `{Scenario}` — test scenario (e.g., Valid Request, Missing Name, Without Authorization)
+
+Examples:
+- `### Users - Create User - Valid Request`
+- `### Users - Get User - Non-existent`
+- `### Users - Delete User - Without Authorization`
+
+## Required Headers
+
+Every request must include:
+```
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+```
+
+For requests with body, also include:
+```
+Content-Type: application/json
+```
+
+## Response Handlers
+
+Every request must have a `client.test()` response handler asserting the expected status code:
+
+```
+### Users - Create User - Valid Request
+POST {{baseUrl}}/api/v4/users
+Authorization: Bearer {{$auth.token("app")}}
+Content-Type: application/json
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+
+{
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+
+> {%
+    client.test("Returns 201 Created", function () {
+        client.assert(response.status === 201, "Expected 201, got " + response.status);
+    });
+
+    client.global.set("userId", response.body.data.id);
+%}
+```
+
+## Passing Data Between Requests
+
+Use `client.global.set()` to save IDs or values from responses:
+
+```javascript
+// In create request handler:
+client.global.set("userId", response.body.data.id);
+
+// In subsequent request URL:
+GET {{baseUrl}}/api/v4/users/{{userId}}
+```
+
+## Test Coverage Checklist
+
+For each endpoint, include tests for:
+
+| Scenario | Expected Status |
+|----------|----------------|
+| Valid request (happy path) | 200 / 201 / 204 |
+| Validation errors (missing/invalid fields) | 422 |
+| Resource not found | 404 |
+| Without authorization (no `Authorization` header) | 401 |
+| Business logic errors | 400 |
+
+## Things to Avoid
+
+- Do **not** use `### ===...` section separators — they render as separate empty requests in PhpStorm's test runner
+- Do **not** hardcode entity IDs — use `client.global.set()` / `client.global.get()` from a create request
+- Do **not** create `http-client.env.json` manually — copy from the example file in project root
+
+## Full Example
+
+```
+### Users - Create User - Valid Request
+POST {{baseUrl}}/api/v4/users
+Authorization: Bearer {{$auth.token("app")}}
+Content-Type: application/json
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+
+{
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+
+> {%
+    client.test("Returns 201 Created", function () {
+        client.assert(response.status === 201, "Expected 201, got " + response.status);
+    });
+
+    client.global.set("userId", response.body.data.id);
+%}
+
+### Users - Create User - Missing Name
+POST {{baseUrl}}/api/v4/users
+Authorization: Bearer {{$auth.token("app")}}
+Content-Type: application/json
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+
+{
+  "email": "john@example.com"
+}
+
+> {%
+    client.test("Returns 422 validation error", function () {
+        client.assert(response.status === 422, "Expected 422, got " + response.status);
+    });
+%}
+
+### Users - Create User - Without Authorization
+POST {{baseUrl}}/api/v4/users
+Content-Type: application/json
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+
+{
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+
+> {%
+    client.test("Returns 401 Unauthorized", function () {
+        client.assert(response.status === 401, "Expected 401, got " + response.status);
+    });
+%}
+
+### Users - Get User - By ID
+GET {{baseUrl}}/api/v4/users/{{userId}}
+Authorization: Bearer {{$auth.token("app")}}
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+
+> {%
+    client.test("Returns 200 OK", function () {
+        client.assert(response.status === 200, "Expected 200, got " + response.status);
+    });
+%}
+
+### Users - Delete User - Valid Request
+DELETE {{baseUrl}}/api/v4/users/{{userId}}
+Authorization: Bearer {{$auth.token("app")}}
+Accept: application/json
+X-Requested-With: XMLHttpRequest
+
+> {%
+    client.test("Returns 200 OK (deleted)", function () {
+        client.assert(response.status === 200, "Expected 200, got " + response.status);
+    });
+%}
+```