@jaimevalasek/aioson 1.3.0

package/template/.aioson/skills/static/jetstream-setup.md

@@ -0,0 +1,200 @@
+# Jetstream Setup
+
+> Laravel Jetstream scaffolds authentication, teams, API tokens, and profile management. Decide at project creation.
+
+---
+
+## Decision: Inertia vs Blade
+
+Make this choice before `artisan jetstream:install` — it cannot be changed without reinstalling.
+
+| Factor | Blade + Livewire | Inertia + Vue/React |
+|---|---|---|
+| Team skillset | PHP-first | JS-first |
+| SPA behavior needed? | No | Yes |
+| Existing Livewire investment? | Yes → Blade | No |
+| Complex client-side state? | No | Yes |
+| SEO critical? | Both work | Both work (with SSR) |
+
+---
+
+## Installation
+
+```bash
+# Blade + Livewire (most common for TALL stack)
+composer require laravel/jetstream
+php artisan jetstream:install livewire --teams   # omit --teams if not needed
+npm install && npm run build
+php artisan migrate
+
+# Inertia + Vue
+php artisan jetstream:install inertia --teams
+npm install && npm run build
+php artisan migrate
+```
+
+---
+
+## Teams — use only when multi-tenant is required
+
+Teams give each user an isolated workspace. Enable only if your domain genuinely needs it.
+
+```php
+// Check if the current user belongs to a team
+auth()->user()->currentTeam->name;
+
+// Add a custom field to teams
+// database/migrations/xxxx_add_plan_to_teams.php
+Schema::table('teams', function (Blueprint $table) {
+    $table->string('plan')->default('free');
+    $table->integer('member_limit')->default(3);
+});
+
+// Team model customization
+// app/Models/Team.php
+class Team extends JetstreamTeam
+{
+    protected $fillable = ['name', 'personal_team', 'plan', 'member_limit'];
+
+    public function hasAvailableSlots(): bool
+    {
+        return $this->users()->count() < $this->member_limit;
+    }
+}
+```
+
+---
+
+## Roles and permissions (Teams)
+
+```php
+// Define in JetstreamServiceProvider
+Jetstream::defaultApiTokenPermissions(['read']);
+
+Jetstream::role('admin', 'Administrator', [
+    'create', 'read', 'update', 'delete',
+])->description('Administrators have full control.');
+
+Jetstream::role('editor', 'Editor', [
+    'create', 'read', 'update',
+])->description('Editors can create and edit content.');
+
+// Check in controllers
+if (! $request->user()->hasTeamRole($team, 'admin')) {
+    abort(403);
+}
+
+// Check in Policies
+public function update(User $user, Post $post): bool
+{
+    return $user->hasTeamPermission($post->team, 'update');
+}
+```
+
+---
+
+## API tokens
+
+```php
+// Token creation is built-in via Jetstream UI
+// Access in routes
+Route::middleware(['auth:sanctum'])->group(function () {
+    Route::get('/api/appointments', [AppointmentController::class, 'index']);
+});
+
+// Check specific token permissions
+Route::middleware(['auth:sanctum'])->group(function () {
+    Route::post('/api/appointments', [AppointmentController::class, 'store'])
+        ->middleware('can:create,App\Models\Appointment');
+});
+```
+
+---
+
+## Profile customization
+
+Add fields to the profile update form:
+
+```php
+// app/Actions/Fortify/UpdateUserProfileInformation.php
+public function update(User $user, array $input): void
+{
+    Validator::make($input, [
+        'name'  => ['required', 'string', 'max:255'],
+        'email' => ['required', 'email', 'unique:users,email,' . $user->id],
+        'phone' => ['nullable', 'string', 'max:20'],  // custom field
+    ])->validateWithBag('updateProfileInformation');
+
+    if (isset($input['photo'])) {
+        $user->updateProfilePhoto($input['photo']);
+    }
+
+    $user->forceFill([
+        'name'  => $input['name'],
+        'email' => $input['email'],
+        'phone' => $input['phone'] ?? null,
+    ])->save();
+}
+```
+
+---
+
+## Two-factor authentication
+
+Jetstream includes 2FA via TOTP out of the box.
+
+```php
+// Require 2FA for admin routes
+Route::middleware(['auth', 'verified', '2fa'])->group(function () {
+    Route::get('/admin', AdminController::class);
+});
+
+// Force users to confirm password before sensitive actions
+Route::middleware(['auth', 'password.confirm'])->group(function () {
+    Route::delete('/account', [AccountController::class, 'destroy']);
+});
+```
+
+---
+
+## Middleware stack understanding
+
+```php
+// web.php — routes available to all
+Route::middleware(['web'])->group(function () { ... });
+
+// Authenticated routes
+Route::middleware(['auth', 'verified'])->group(function () { ... });
+
+// Team-scoped routes
+Route::middleware(['auth', 'verified', EnsureUserHasTeam::class])->group(function () { ... });
+```
+
+---
+
+## Custom views — override Jetstream defaults
+
+```bash
+php artisan vendor:publish --tag=jetstream-views
+# Publishes to resources/views/vendor/jetstream/
+```
+
+Override only the views you need. Keep Jetstream's Action classes unless you need custom logic.
+
+---
+
+## Post-install checklist
+
+- [ ] Choose Livewire or Inertia (cannot change later)
+- [ ] Decide on Teams before first migration
+- [ ] Configure `FILESYSTEM_DISK` for profile photos (`public` or `s3`)
+- [ ] Set `MAIL_*` env vars — email verification requires working mail
+- [ ] Update `JetstreamServiceProvider` with roles/permissions
+- [ ] Customize `UpdateUserProfileInformation` if adding custom fields
+- [ ] Override views for custom branding
+
+## NEVER
+- Install Jetstream into an existing project without checking for migration conflicts
+- Enable Teams if the domain does not genuinely need multi-tenancy
+- Modify Jetstream Action classes unless customization is explicitly required
+- Mix Jetstream auth with another auth package (Breeze, Fortify standalone) in the same app

package/template/.aioson/skills/static/laravel-conventions.md

@@ -0,0 +1,491 @@
+# Laravel Conventions
+
+> Production-grade Laravel. Thin controllers. Explicit intent. No shortcuts.
+
+---
+
+## Project structure
+
+```
+myproject/
+├── app/
+│   ├── Actions/              # Business logic — one class per operation
+│   ├── Console/
+│   │   └── Commands/
+│   ├── Events/
+│   ├── Exceptions/
+│   ├── Http/
+│   │   ├── Controllers/      # HTTP orchestration only
+│   │   ├── Middleware/
+│   │   └── Requests/         # Form Request classes (validation)
+│   ├── Jobs/
+│   ├── Listeners/
+│   ├── Mail/
+│   ├── Models/               # Eloquent models (singular class name)
+│   ├── Notifications/
+│   ├── Policies/
+│   ├── Providers/
+│   └── View/
+│       └── Components/       # Blade components
+├── database/
+│   ├── factories/
+│   ├── migrations/
+│   └── seeders/
+├── resources/
+│   ├── views/
+│   │   ├── users/            # Plural folder per resource
+│   │   │   ├── index.blade.php
+│   │   │   ├── show.blade.php
+│   │   │   ├── create.blade.php
+│   │   │   └── edit.blade.php
+│   │   ├── components/
+│   │   └── layouts/
+│   └── js/
+├── routes/
+│   ├── web.php
+│   └── api.php
+└── tests/
+    ├── Feature/
+    └── Unit/
+```
+
+**With Jetstream + Livewire** — additional folders:
+```
+app/
+└── Livewire/
+    ├── Auth/
+    └── Users/                # Group components by domain
+        ├── UserList.php
+        └── EditUser.php
+resources/views/
+└── livewire/
+    ├── auth/
+    └── users/
+        ├── user-list.blade.php   # kebab-case filename matches component
+        └── edit-user.blade.php
+```
+
+---
+
+## Naming conventions
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Model | Singular, PascalCase | `User`, `BlogPost` |
+| Table | Plural, snake_case | `users`, `blog_posts` |
+| Controller | Singular model + `Controller` | `UserController`, `BlogPostController` |
+| Form Request | Action + model | `CreateUserRequest`, `UpdateUserRequest` |
+| Action | Verb + noun + `Action` | `CreateUserAction`, `SendWelcomeEmailAction` |
+| Policy | Singular model + `Policy` | `UserPolicy` |
+| Event | Past-tense noun phrase | `UserCreated`, `OrderShipped` |
+| Listener | Present verb phrase | `SendWelcomeEmail`, `NotifyAdminOfOrder` |
+| Job | Imperative verb phrase | `GenerateInvoice`, `ProcessPayment` |
+| API Resource | Singular model + `Resource` | `UserResource` |
+| Livewire component class | PascalCase, singular or descriptive | `UserList`, `EditUser` |
+| Livewire component file | kebab-case matching class | `user-list.blade.php` |
+| View folder | Plural, kebab-case | `users/`, `blog-posts/` |
+| Route URI | Plural, kebab-case | `/users`, `/blog-posts` |
+| Migration | `create_table_table`, `add_col_to_table` | `create_users_table` |
+
+**Singular vs plural rule of thumb:**
+- Class names → **singular** (represents one record: `User`, `Order`)
+- Folders grouping multiple files → **plural** (`Controllers/`, `Models/`, `views/users/`)
+- Database tables and route URIs → **plural** (`users`, `/orders`)
+
+---
+
+## Controllers — HTTP orchestration only
+
+Controllers validate the request, call an Action, and return a response. Nothing else.
+
+```php
+// WRONG — business logic in controller
+public function store(Request $request)
+{
+    if (Appointment::where('doctor_id', $request->doctor_id)
+        ->whereDate('date', $request->date)->exists()) {
+        return back()->withErrors(['date' => 'Already booked.']);
+    }
+    $appointment = Appointment::create([...]);
+    Mail::to(auth()->user())->send(new AppointmentConfirmed($appointment));
+    return redirect()->route('appointments.index');
+}
+
+// RIGHT — controller as orchestrator
+public function store(CreateAppointmentRequest $request): RedirectResponse
+{
+    $appointment = (new CreateAppointmentAction)->execute(
+        auth()->user(),
+        AppointmentData::fromRequest($request)
+    );
+    return redirect()->route('appointments.show', $appointment);
+}
+```
+
+---
+
+## Form Requests — all validation lives here
+
+```php
+class CreateAppointmentRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('create', Appointment::class);
+    }
+
+    public function rules(): array
+    {
+        return [
+            'doctor_id' => ['required', 'exists:doctors,id'],
+            'date'      => ['required', 'date', 'after:today'],
+            'notes'     => ['nullable', 'string', 'max:500'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'date.after' => 'The appointment must be scheduled for a future date.',
+        ];
+    }
+}
+```
+
+---
+
+## Actions — one class, one business operation
+
+```php
+// app/Actions/CreateAppointmentAction.php
+class CreateAppointmentAction
+{
+    public function execute(User $user, AppointmentData $data): Appointment
+    {
+        $this->ensureNoConflict($data->doctorId, $data->date);
+
+        $appointment = Appointment::create([
+            'user_id'   => $user->id,
+            'doctor_id' => $data->doctorId,
+            'date'      => $data->date,
+            'notes'     => $data->notes,
+        ]);
+
+        AppointmentCreated::dispatch($appointment);
+
+        return $appointment;
+    }
+
+    private function ensureNoConflict(int $doctorId, Carbon $date): void
+    {
+        if (Appointment::where('doctor_id', $doctorId)
+            ->whereDate('date', $date)
+            ->where('status', '!=', 'cancelled')
+            ->exists()) {
+            throw new AppointmentConflictException();
+        }
+    }
+}
+```
+
+---
+
+## Policies — authorization layer, not inside Actions
+
+```php
+class AppointmentPolicy
+{
+    public function view(User $user, Appointment $appointment): bool
+    {
+        return $user->id === $appointment->user_id
+            || $user->hasRole('admin');
+    }
+
+    public function cancel(User $user, Appointment $appointment): bool
+    {
+        return $this->view($user, $appointment)
+            && $appointment->date->isAfter(now()->addHours(24));
+    }
+}
+```
+
+Call via `$this->authorize('cancel', $appointment)` in controllers or Form Requests.
+
+---
+
+## Events + Listeners — side effects always async/queued
+
+Never call external services synchronously inside an Action.
+
+```php
+// Event — carries minimum required data
+class AppointmentCreated
+{
+    use Dispatchable, SerializesModels;
+    public function __construct(public readonly Appointment $appointment) {}
+}
+
+// Listener — always queued
+class SendConfirmationEmail implements ShouldQueue
+{
+    public int $tries = 3;
+
+    public function handle(AppointmentCreated $event): void
+    {
+        Mail::to($event->appointment->user)
+            ->send(new AppointmentConfirmedMail($event->appointment));
+    }
+}
+```
+
+---
+
+## Jobs — long-running or retriable work
+
+```php
+class GenerateInvoiceJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public int $backoff = 60;
+
+    public function __construct(private readonly Order $order) {}
+
+    public function handle(InvoiceService $service): void
+    {
+        $service->generate($this->order);
+    }
+
+    public function failed(Throwable $e): void
+    {
+        Log::error('Invoice generation failed', [
+            'order_id' => $this->order->id,
+            'error'    => $e->getMessage(),
+        ]);
+    }
+}
+```
+
+---
+
+## API Resources — always transform, never expose raw models
+
+```php
+class AppointmentResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id'     => $this->id,
+            'date'   => $this->date->toIso8601String(),
+            'status' => $this->status,
+            'doctor' => new DoctorResource($this->whenLoaded('doctor')),
+            'can'    => [
+                'cancel' => $request->user()->can('cancel', $this->resource),
+            ],
+        ];
+    }
+}
+```
+
+---
+
+## N+1 prevention
+
+```php
+// WRONG — N+1 (one query per row)
+$appointments = Appointment::all();
+foreach ($appointments as $a) { echo $a->doctor->name; }
+
+// RIGHT — eager loading
+$appointments = Appointment::with(['doctor.user', 'patient'])->paginate(20);
+
+// Define reusable scope on the model
+public function scopeWithRelations(Builder $query): Builder
+{
+    return $query->with(['doctor.user', 'patient']);
+}
+```
+
+Use Laravel Debugbar or Telescope in dev to catch N+1 before production.
+
+---
+
+## Model conventions
+
+```php
+class Appointment extends Model
+{
+    protected $fillable = ['user_id', 'doctor_id', 'date', 'status', 'notes'];
+
+    protected $casts = [
+        'date'         => 'datetime',
+        'cancelled_at' => 'datetime',
+    ];
+
+    public function scopePending(Builder $query): Builder
+    {
+        return $query->where('status', 'pending');
+    }
+
+    public function scopeUpcoming(Builder $query): Builder
+    {
+        return $query->where('date', '>', now())->orderBy('date');
+    }
+
+    public function doctor(): BelongsTo
+    {
+        return $this->belongsTo(Doctor::class);
+    }
+}
+```
+
+---
+
+## Migrations
+
+- One migration per schema change — never edit after deployment.
+- Always add foreign key constraints.
+- Name columns after the domain: `cancelled_at`, not `is_cancelled_timestamp`.
+- Add indexes for columns used in WHERE clauses and ORDER BY.
+
+```php
+Schema::create('appointments', function (Blueprint $table) {
+    $table->id();
+    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+    $table->foreignId('doctor_id')->constrained()->restrictOnDelete();
+    $table->dateTime('date');
+    $table->enum('status', ['pending', 'confirmed', 'cancelled'])->default('pending');
+    $table->text('notes')->nullable();
+    $table->timestamp('cancelled_at')->nullable();
+    $table->timestamps();
+
+    $table->index(['doctor_id', 'date']); // for conflict checks
+});
+```
+
+---
+
+## Testing
+
+```php
+// Feature — test full HTTP layer
+test('patient can book appointment', function () {
+    $patient = User::factory()->create();
+    $doctor  = Doctor::factory()->create();
+
+    actingAs($patient)
+        ->post(route('appointments.store'), [
+            'doctor_id' => $doctor->id,
+            'date'      => now()->addDay()->toDateTimeString(),
+        ])
+        ->assertRedirect();
+
+    expect(Appointment::where('user_id', $patient->id)->exists())->toBeTrue();
+});
+
+// Unit — test Actions in isolation
+test('CreateAppointmentAction throws on conflict', function () {
+    $existing = Appointment::factory()->confirmed()->create();
+
+    expect(fn () => (new CreateAppointmentAction)->execute(
+        $existing->user,
+        AppointmentData::from(['doctor_id' => $existing->doctor_id, 'date' => $existing->date])
+    ))->toThrow(AppointmentConflictException::class);
+});
+```
+
+---
+
+## Livewire components (Jetstream stack)
+
+Livewire replaces full-page controllers for interactive UI. Use it instead of writing separate Vue/React components when the project is on the Jetstream+Livewire stack.
+
+```php
+// app/Livewire/Users/UserList.php
+namespace App\Livewire\Users;
+
+use Livewire\Component;
+use Livewire\WithPagination;
+use Livewire\Attributes\Computed;
+
+class UserList extends Component
+{
+    use WithPagination;
+
+    public string $search = '';
+
+    // Computed property — recalculates automatically when $search changes
+    #[Computed]
+    public function users(): \Illuminate\Contracts\Pagination\LengthAwarePaginator
+    {
+        return User::query()
+            ->when($this->search, fn ($q) => $q->where('name', 'like', "%{$this->search}%"))
+            ->paginate(10);
+    }
+
+    public function render(): \Illuminate\View\View
+    {
+        return view('livewire.users.user-list');
+    }
+}
+```
+
+```blade
+{{-- resources/views/livewire/users/user-list.blade.php --}}
+<div>
+    <input wire:model.live="search" type="text" placeholder="Search…" />
+
+    @foreach ($this->users as $user)
+        <div>{{ $user->name }}</div>
+    @endforeach
+
+    {{ $this->users->links() }}
+</div>
+```
+
+**Livewire conventions:**
+- Class in `app/Livewire/<Domain>/ClassName.php` (PascalCase)
+- View in `resources/views/livewire/<domain>/class-name.blade.php` (kebab-case)
+- Use `#[Computed]` for derived data — never store computed values in public properties
+- Use `wire:model.live` for real-time search; `wire:model.lazy` for form inputs (debounce on blur)
+- Keep business logic in Actions — Livewire component only wires input → Action → response
+- Never query DB inside Blade template — use `#[Computed]` property
+
+**Classic controller variant (same project, non-Livewire views):**
+```php
+// app/Http/Controllers/UserController.php
+class UserController extends Controller
+{
+    public function index(Request $request): View
+    {
+        $users = User::query()
+            ->when($request->search, fn ($q) => $q->where('name', 'like', "%{$request->search}%"))
+            ->paginate(10);
+
+        return view('users.index', compact('users'));
+    }
+}
+```
+
+Both patterns coexist fine in a Jetstream project — Livewire for interactive pages, classic controllers for simple read-only or API routes.
+
+---
+
+## ALWAYS
+- Form Requests for validation
+- Actions for business logic
+- Policies for authorization
+- Events + queued Listeners for side effects
+- API Resources for JSON responses
+- Eager loading with `with()`
+- Follow naming conventions: singular classes, plural tables and view folders
+
+## NEVER
+- Business logic in controllers
+- `Mail::send()` synchronously in request cycle
+- `Auth::user()` inside an Action (inject `User` instead)
+- Raw `DB::table()` queries bypassing Eloquent in feature code
+- Exposing Eloquent models directly in API responses
+- Queries inside Blade or Livewire templates directly (use `#[Computed]` or pass via controller)