@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/laravel/examples/02-queue-job-with-retry-and-events.md

@@ -1,229 +0,0 @@
-# Example: Queue Job with Retry Logic and Event Dispatch
-
-## Scenario
-
-Process a payment through a third-party API asynchronously. The job must retry with exponential backoff, notify an admin on permanent failure, and fire an event after successful payment so downstream listeners can handle side effects independently.
-
-## Queued Job
-
-```php
-// app/Jobs/ProcessPayment.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Jobs;
-
-use App\Events\PaymentCompleted;
-use App\Models\Order;
-use App\Notifications\PaymentFailedNotification;
-use App\Services\PaymentGateway;
-use Illuminate\Bus\Queueable;
-use Illuminate\Contracts\Queue\ShouldQueue;
-use Illuminate\Foundation\Bus\Dispatchable;
-use Illuminate\Queue\InteractsWithQueue;
-use Illuminate\Queue\SerializesModels;
-use Illuminate\Support\Facades\Log;
-use Illuminate\Support\Facades\Notification;
-use Throwable;
-
-class ProcessPayment implements ShouldQueue
-{
-    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
-
-    public int $tries = 5;
-
-    public int $maxExceptions = 3;
-
-    public int $timeout = 30;
-
-    public function __construct(
-        public readonly Order $order,
-    ) {}
-
-    /**
-     * Exponential backoff: 10s, 30s, 90s, 270s, 810s.
-     */
-    public function backoff(): array
-    {
-        return [10, 30, 90, 270, 810];
-    }
-
-    public function handle(PaymentGateway $gateway): void
-    {
-        Log::info('Processing payment', ['order_id' => $this->order->id]);
-
-        $result = $gateway->charge(
-            amount: $this->order->total_cents,
-            currency: 'usd',
-            customerId: $this->order->customer->stripe_id,
-        );
-
-        $this->order->update([
-            'status'             => 'paid',
-            'payment_reference'  => $result->transactionId,
-        ]);
-
-        event(new PaymentCompleted($this->order));
-    }
-
-    public function failed(Throwable $exception): void
-    {
-        Log::error('Payment failed permanently', [
-            'order_id'  => $this->order->id,
-            'error'     => $exception->getMessage(),
-        ]);
-
-        $this->order->update(['status' => 'payment_failed']);
-
-        Notification::route('mail', config('app.admin_email'))
-            ->notify(new PaymentFailedNotification($this->order, $exception));
-    }
-}
-```
-
-## Event and Listener
-
-```php
-// app/Events/PaymentCompleted.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Events;
-
-use App\Models\Order;
-use Illuminate\Foundation\Events\Dispatchable;
-use Illuminate\Queue\SerializesModels;
-
-class PaymentCompleted
-{
-    use Dispatchable, SerializesModels;
-
-    public function __construct(
-        public readonly Order $order,
-    ) {}
-}
-```
-
-```php
-// app/Listeners/SendPaymentReceipt.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Listeners;
-
-use App\Events\PaymentCompleted;
-use App\Notifications\PaymentReceiptNotification;
-use Illuminate\Contracts\Queue\ShouldQueue;
-
-class SendPaymentReceipt implements ShouldQueue
-{
-    public function handle(PaymentCompleted $event): void
-    {
-        $event->order->customer->notify(
-            new PaymentReceiptNotification($event->order)
-        );
-    }
-}
-```
-
-## Controller Dispatch
-
-```php
-// app/Http/Controllers/Api/PaymentController.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Controllers\Api;
-
-use App\Http\Controllers\Controller;
-use App\Http\Requests\CreatePaymentRequest;
-use App\Jobs\ProcessPayment;
-use App\Models\Order;
-use Illuminate\Http\JsonResponse;
-use Symfony\Component\HttpFoundation\Response;
-
-class PaymentController extends Controller
-{
-    public function store(CreatePaymentRequest $request, Order $order): JsonResponse
-    {
-        $this->authorize('pay', $order);
-
-        $order->update(['status' => 'processing']);
-
-        ProcessPayment::dispatch($order);
-
-        return response()->json(
-            ['message' => 'Payment is being processed.', 'order_id' => $order->id],
-            Response::HTTP_ACCEPTED,
-        );
-    }
-}
-```
-
-## Feature Test
-
-```php
-// tests/Feature/ProcessPaymentTest.php
-<?php
-
-declare(strict_types=1);
-
-namespace Tests\Feature;
-
-use App\Events\PaymentCompleted;
-use App\Jobs\ProcessPayment;
-use App\Models\Order;
-use Illuminate\Foundation\Testing\RefreshDatabase;
-use Illuminate\Support\Facades\Event;
-use Illuminate\Support\Facades\Queue;
-use Tests\TestCase;
-
-class ProcessPaymentTest extends TestCase
-{
-    use RefreshDatabase;
-
-    public function test_payment_endpoint_dispatches_job(): void
-    {
-        Queue::fake();
-
-        $order = Order::factory()->create(['status' => 'pending']);
-        $user = $order->customer->user;
-
-        $this->actingAs($user)
-            ->postJson("/api/orders/{$order->id}/pay")
-            ->assertStatus(202);
-
-        Queue::assertPushed(ProcessPayment::class, function ($job) use ($order) {
-            return $job->order->id === $order->id;
-        });
-    }
-
-    public function test_successful_payment_fires_event(): void
-    {
-        Event::fake([PaymentCompleted::class]);
-
-        $order = Order::factory()->create(['status' => 'processing']);
-
-        // Simulate the job running synchronously in tests
-        (new ProcessPayment($order))->handle(
-            app(\App\Services\PaymentGateway::class)
-        );
-
-        Event::assertDispatched(PaymentCompleted::class, function ($event) use ($order) {
-            return $event->order->id === $order->id;
-        });
-    }
-}
-```
-
-## Key Decisions
-
-- **Exponential backoff**: The stepped array `[10, 30, 90, 270, 810]` gives the third-party API increasing recovery time.
-- **`maxExceptions = 3`**: Caps distinct exception types to avoid burning retries on the same unrecoverable error.
-- **`failed()` notifies admin**: Permanent failures need human attention; logging alone is insufficient for payment processing.
-- **Event decoupling**: `PaymentCompleted` lets receipt emails, inventory updates, and analytics run independently without bloating the job.
-- **HTTP 202 Accepted**: The controller acknowledges the request without waiting for payment completion.

package/workflows/skills/laravel/references/eloquent.md

@@ -1,200 +0,0 @@
-# Eloquent ORM Reference
-
-## Model Definition Patterns
-
-### Fillable vs Guarded
-
-Always declare `$fillable` explicitly. Never rely on an empty `$guarded = []` in production
-because it opens every column to mass assignment.
-
-```php
-// Correct: explicit allow-list
-protected $fillable = ['name', 'email', 'role'];
-
-// Dangerous: allows mass assignment of any column including is_admin
-protected $guarded = [];
-```
-
-### Casts and Accessors
-
-Use `$casts` for type coercion. Use Attribute accessors (Laravel 11 syntax) for
-computed values that do not map to a database column.
-
-```php
-protected function casts(): array
-{
-    return [
-        'email_verified_at' => 'datetime',
-        'settings'          => 'array',
-        'amount_cents'      => 'integer',
-        'is_active'         => 'boolean',
-    ];
-}
-
-protected function fullName(): Attribute
-{
-    return Attribute::make(
-        get: fn () => "{$this->first_name} {$this->last_name}",
-    );
-}
-```
-
-## Relationships
-
-### Defining Relationships
-
-Always type-hint return types on relationship methods. Eloquent uses the method
-return type for IDE support and static analysis.
-
-```php
-public function posts(): HasMany
-{
-    return $this->hasMany(Post::class);
-}
-
-public function profile(): HasOne
-{
-    return $this->hasOne(Profile::class);
-}
-
-public function roles(): BelongsToMany
-{
-    return $this->belongsToMany(Role::class)
-        ->withPivot('assigned_at')
-        ->withTimestamps();
-}
-```
-
-### Polymorphic Relationships
-
-Use morphTo/morphMany for tagging, commenting, and media attachment patterns.
-
-```php
-// On the Comment model
-public function commentable(): MorphTo
-{
-    return $this->morphTo();
-}
-
-// On the Post model
-public function comments(): MorphMany
-{
-    return $this->morphMany(Comment::class, 'commentable');
-}
-```
-
-## Eager Loading
-
-### Preventing N+1 Queries
-
-Use `with()` at query time. Use `load()` on an existing model instance.
-
-```php
-// At query time (preferred)
-$orders = Order::with(['customer', 'items.product'])->get();
-
-// On an existing instance (e.g., route-model binding)
-$order->load(['customer', 'items.product']);
-```
-
-### Constraining Eager Loads
-
-Filter related models without affecting the parent query.
-
-```php
-$users = User::with(['posts' => function (Builder $query) {
-    $query->where('published', true)->latest()->limit(5);
-}])->get();
-```
-
-### Preventing Lazy Loading in Development
-
-Add this to `AppServiceProvider::boot()` to catch N+1 queries during development.
-
-```php
-Model::preventLazyLoading(! app()->isProduction());
-```
-
-## Query Scopes
-
-### Local Scopes
-
-Encapsulate reusable query constraints.
-
-```php
-public function scopeActive(Builder $query): Builder
-{
-    return $query->where('is_active', true);
-}
-
-public function scopeCreatedAfter(Builder $query, Carbon $date): Builder
-{
-    return $query->where('created_at', '>=', $date);
-}
-
-// Usage
-$users = User::active()->createdAfter(now()->subMonth())->get();
-```
-
-### Global Scopes
-
-Apply constraints automatically to every query on a model. Use sparingly
-because they affect all queries including relationships.
-
-```php
-protected static function booted(): void
-{
-    static::addGlobalScope('active', function (Builder $builder) {
-        $builder->where('is_active', true);
-    });
-}
-```
-
-## Factories and Seeders
-
-### Factory Definition (Laravel 11)
-
-```php
-class OrderFactory extends Factory
-{
-    public function definition(): array
-    {
-        return [
-            'customer_id' => Customer::factory(),
-            'status'       => fake()->randomElement(['pending', 'paid', 'shipped']),
-            'total_cents'  => fake()->numberBetween(1000, 500000),
-        ];
-    }
-
-    public function paid(): static
-    {
-        return $this->state(['status' => 'paid']);
-    }
-
-    public function withItems(int $count = 3): static
-    {
-        return $this->has(OrderItem::factory()->count($count));
-    }
-}
-
-// Usage in tests
-$order = Order::factory()->paid()->withItems(5)->create();
-```
-
-## Performance Patterns
-
-- Use `select()` to limit columns when you do not need the full model.
-- Use `chunk()` or `lazy()` for processing large datasets to control memory.
-- Use `toBase()` when you need raw stdClass objects without model hydration.
-- Index foreign keys and columns used in `where`, `orderBy`, and `groupBy`.
-- Use `explain()` to inspect query plans during development.
-
-```php
-// Memory-efficient processing
-Order::where('status', 'pending')
-    ->chunkById(500, function (Collection $orders) {
-        foreach ($orders as $order) {
-            ProcessOrder::dispatch($order);
-        }
-    });
-```

package/workflows/skills/laravel/references/middleware-routing.md

@@ -1,243 +0,0 @@
-# Middleware and Routing Reference
-
-## Route Definition
-
-### API Routes (Laravel 11)
-
-Laravel 11 uses `routes/api.php` loaded by `bootstrap/app.php`. The `/api` prefix
-is applied automatically.
-
-```php
-// bootstrap/app.php
-return Application::configure(basePath: dirname(__DIR__))
-    ->withRouting(
-        api: __DIR__ . '/../routes/api.php',
-        apiPrefix: 'api/v1',
-    )
-    ->create();
-```
-
-### Resource Routes
-
-Use `apiResource` for API-only routes (excludes `create` and `edit` form routes).
-
-```php
-Route::apiResource('orders', OrderController::class);
-
-// Restricting to specific actions
-Route::apiResource('orders', OrderController::class)
-    ->only(['index', 'show', 'store']);
-
-// Nested resources
-Route::apiResource('orders.items', OrderItemController::class)
-    ->shallow();
-```
-
-### Route Groups
-
-Group routes by shared middleware, prefix, or namespace.
-
-```php
-Route::prefix('admin')
-    ->middleware(['auth:sanctum', 'role:admin'])
-    ->group(function () {
-        Route::apiResource('users', AdminUserController::class);
-        Route::post('users/{user}/impersonate', ImpersonateController::class);
-    });
-```
-
-## Middleware
-
-### Built-in Middleware (Laravel 11)
-
-Laravel 11 consolidates middleware configuration in `bootstrap/app.php`.
-
-```php
-return Application::configure(basePath: dirname(__DIR__))
-    ->withMiddleware(function (Middleware $middleware) {
-        $middleware->api(prepend: [
-            EnsureJsonResponse::class,
-        ]);
-
-        $middleware->alias([
-            'role'     => EnsureUserHasRole::class,
-            'throttle' => ThrottleRequests::class,
-        ]);
-
-        $middleware->throttleWithRedis();
-    })
-    ->create();
-```
-
-### Writing Custom Middleware
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Middleware;
-
-use Closure;
-use Illuminate\Http\Request;
-use Symfony\Component\HttpFoundation\Response;
-
-class EnsureTenantScope
-{
-    public function handle(Request $request, Closure $next): Response
-    {
-        $tenantId = $request->header('X-Tenant-ID');
-
-        if (! $tenantId) {
-            return response()->json(
-                ['error' => 'Missing X-Tenant-ID header'],
-                Response::HTTP_BAD_REQUEST,
-            );
-        }
-
-        // Bind tenant context for the request lifecycle
-        app()->instance('tenant.id', (int) $tenantId);
-
-        return $next($request);
-    }
-}
-```
-
-### Middleware Ordering
-
-Middleware executes in the order registered. Place authentication before
-authorization, and authorization before business-logic middleware.
-
-```
-1. ThrottleRequests       — reject floods before spending auth work
-2. Authenticate           — verify identity
-3. EnsureTenantScope      — resolve tenant from header
-4. AuthorizeTenantAccess  — verify user belongs to tenant
-5. Business middleware    — logging, feature flags, etc.
-```
-
-## Rate Limiting
-
-### Defining Rate Limiters
-
-```php
-// bootstrap/app.php or AppServiceProvider
-RateLimiter::for('api', function (Request $request) {
-    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
-});
-
-RateLimiter::for('uploads', function (Request $request) {
-    return $request->user()?->isPremium()
-        ? Limit::perMinute(30)
-        : Limit::perMinute(5);
-});
-```
-
-### Applying Rate Limiters
-
-```php
-Route::middleware('throttle:api')->group(function () {
-    Route::apiResource('posts', PostController::class);
-});
-
-Route::middleware('throttle:uploads')->post('files', FileUploadController::class);
-```
-
-## Request Validation
-
-### Form Request Classes
-
-Always use Form Request classes instead of inline validation. They centralize
-validation rules, authorization checks, and custom error messages.
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Requests;
-
-use Illuminate\Foundation\Http\FormRequest;
-
-class StoreOrderRequest extends FormRequest
-{
-    public function authorize(): bool
-    {
-        return $this->user()->can('create', Order::class);
-    }
-
-    public function rules(): array
-    {
-        return [
-            'customer_id'               => ['required', 'exists:customers,id'],
-            'items'                     => ['required', 'array', 'min:1'],
-            'items.*.product_id'        => ['required', 'exists:products,id'],
-            'items.*.quantity'          => ['required', 'integer', 'min:1', 'max:1000'],
-            'shipping_address'          => ['required', 'string', 'max:500'],
-            'notes'                     => ['nullable', 'string', 'max:2000'],
-        ];
-    }
-
-    public function messages(): array
-    {
-        return [
-            'items.required'              => 'An order must contain at least one item.',
-            'items.*.product_id.exists'   => 'One or more selected products do not exist.',
-        ];
-    }
-}
-```
-
-### Using Form Requests in Controllers
-
-```php
-public function store(StoreOrderRequest $request): OrderResource
-{
-    // Validation and authorization already passed
-    $validated = $request->validated();
-
-    $order = DB::transaction(function () use ($validated) {
-        $order = Order::create(Arr::except($validated, 'items'));
-
-        foreach ($validated['items'] as $item) {
-            $order->items()->create($item);
-        }
-
-        return $order;
-    });
-
-    return new OrderResource($order->load('items.product'));
-}
-```
-
-## Response Patterns
-
-### Consistent JSON Responses
-
-Use API Resources for success responses and exception handlers for errors.
-
-```php
-// Successful creation
-return new OrderResource($order);
-// Returns 200 with resource shape
-
-// Accepted (async processing)
-return response()->json(['message' => 'Processing'], 202);
-
-// No content (delete)
-return response()->noContent();
-```
-
-### Exception Handling
-
-Customize exception rendering in `bootstrap/app.php` (Laravel 11).
-
-```php
-->withExceptions(function (Exceptions $exceptions) {
-    $exceptions->render(function (ModelNotFoundException $e, Request $request) {
-        if ($request->expectsJson()) {
-            return response()->json(['error' => 'Resource not found'], 404);
-        }
-    });
-})
-```