@famgia/omnify-laravel 0.0.87 → 0.0.89

package/stubs/ai-guides/claude-rules/performance.md.stub

@@ -0,0 +1,251 @@
+# Performance & Quality Rules
+
+> **Non-negotiable rules** for Laravel performance and code quality.
+
+## 🟠 N+1 Query Problem
+
+**Always eager load relationships.**
+
+```php
+// ❌ N+1 PROBLEM: 1 + N queries (N = number of posts)
+$posts = Post::all();
+foreach ($posts as $post) {
+    echo $post->author->name;  // Query for each post!
+}
+
+// ✅ CORRECT: Eager loading with with()
+$posts = Post::with('author')->get();
+foreach ($posts as $post) {
+    echo $post->author->name;  // No extra queries
+}
+
+// ✅ CORRECT: Multiple relationships
+$posts = Post::with(['author', 'comments', 'tags'])->get();
+
+// ✅ CORRECT: Nested eager loading
+$posts = Post::with('comments.author')->get();
+```
+
+**Enable N+1 detection in development:**
+
+```php
+// In AppServiceProvider boot()
+use Illuminate\Database\Eloquent\Model;
+
+public function boot(): void
+{
+    // Throw exception on lazy loading (dev only)
+    Model::preventLazyLoading(!app()->isProduction());
+}
+```
+
+---
+
+## 🟠 Use `whenLoaded()` in Resources
+
+**Prevent queries in Resources.**
+
+```php
+// ❌ ERROR: Triggers query if not eager loaded
+class PostResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'author' => new UserResource($this->author),  // N+1!
+        ];
+    }
+}
+
+// ✅ CORRECT: Only include if already loaded
+class PostResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'author' => new UserResource($this->whenLoaded('author')),
+        ];
+    }
+}
+```
+
+---
+
+## 🟠 Pagination for List Endpoints
+
+**Never return all records.**
+
+```php
+// ❌ ERROR: Returns all records (memory + performance)
+public function index()
+{
+    return UserResource::collection(User::all());  // 1M users = crash
+}
+
+// ✅ CORRECT: Always paginate
+public function index(Request $request)
+{
+    $perPage = min($request->input('per_page', 15), 100);  // Max 100
+    return UserResource::collection(User::paginate($perPage));
+}
+```
+
+---
+
+## 🟠 Select Only Needed Columns
+
+**Don't SELECT * when you need few fields.**
+
+```php
+// ❌ INEFFICIENT: Fetches all columns
+$users = User::all();
+$names = $users->pluck('name');
+
+// ✅ EFFICIENT: Select only needed columns
+$names = User::pluck('name');
+
+// ✅ EFFICIENT: For multiple columns
+$users = User::select(['id', 'name', 'email'])->get();
+```
+
+---
+
+## 🟡 Code Quality Rules
+
+### Never Validate in Controller
+
+```php
+// ❌ BAD: Validation in controller
+public function store(Request $request)
+{
+    $validated = $request->validate([...]);
+}
+
+// ✅ CORRECT: Use FormRequest
+public function store(UserStoreRequest $request)
+{
+    $user = User::create($request->validated());
+    return new UserResource($user);
+}
+```
+
+### Always Use Resource for Responses
+
+```php
+// ❌ BAD: Exposes all fields, inconsistent format
+return $user;
+return response()->json($user);
+
+// ✅ CORRECT: Use Resource
+return new UserResource($user);
+return UserResource::collection($users);
+```
+
+### Use Route Model Binding
+
+```php
+// ❌ BAD: Manual find
+public function show(int $id)
+{
+    $user = User::findOrFail($id);
+    return new UserResource($user);
+}
+
+// ✅ CORRECT: Route model binding
+public function show(User $user)
+{
+    return new UserResource($user);
+}
+```
+
+### Use Transactions for Multiple Operations
+
+```php
+// ❌ BAD: Partial failure possible
+$order = Order::create([...]);
+$order->items()->createMany([...]);
+
+// ✅ CORRECT: Transaction ensures atomicity
+DB::transaction(function () use ($data) {
+    $order = Order::create([...]);
+    $order->items()->createMany([...]);
+    return $order;
+});
+```
+
+### Never Use env() Outside Config
+
+```php
+// ❌ BAD: env() won't work with config:cache
+$apiKey = env('API_KEY');
+
+// ✅ CORRECT: Use config()
+$apiKey = config('services.api_key');
+```
+
+---
+
+## 🔵 Date/Time Rules
+
+### Always Store UTC
+
+```php
+// config/app.php
+'timezone' => 'UTC',  // NEVER change this
+
+// ❌ BAD: Store local time
+$event->scheduled_at = Carbon::now('Asia/Tokyo');
+
+// ✅ CORRECT: Store UTC
+$event->scheduled_at = Carbon::now();  // UTC
+```
+
+### Always Return ISO 8601 in API
+
+```php
+// ❌ BAD: Local format
+'created_at' => $this->created_at->format('Y-m-d H:i:s'),
+
+// ✅ CORRECT: ISO 8601 UTC
+'created_at' => $this->created_at?->toISOString(),
+// Output: "2024-01-15T10:30:00.000000Z"
+```
+
+---
+
+## Quick Reference
+
+| Category        | ❌ Never Do                          | ✅ Always Do              |
+| --------------- | ----------------------------------- | ------------------------ |
+| **Performance** | `Model::all()` without limit        | `Model::paginate()`      |
+|                 | Access relation without `with()`    | Eager load with `with()` |
+|                 | `$this->relation` in Resource       | `$this->whenLoaded()`    |
+| **Quality**     | Validate in Controller              | Use FormRequest          |
+|                 | Return Model directly               | Return Resource          |
+|                 | `findOrFail($id)`                   | Route model binding      |
+|                 | Multiple DB ops without transaction | `DB::transaction()`      |
+| **Config**      | `env()` in code                     | `config()`               |
+| **Dates**       | Local timezone                      | UTC everywhere           |
+|                 | `format('Y-m-d')`                   | `->toISOString()`        |
+
+---
+
+## Development Safeguards
+
+Add to `AppServiceProvider::boot()`:
+
+```php
+public function boot(): void
+{
+    // Prevent N+1 queries (throws exception on lazy load)
+    Model::preventLazyLoading(!app()->isProduction());
+    
+    // Prevent accessing missing attributes
+    Model::preventAccessingMissingAttributes(!app()->isProduction());
+    
+    // Prevent silently discarding attributes
+    Model::preventSilentlyDiscardingAttributes(!app()->isProduction());
+}
+```
+
+These will throw exceptions during development, helping you catch issues early.

package/stubs/ai-guides/claude-rules/security.md.stub

@@ -0,0 +1,159 @@
+# Security Rules
+
+> **Non-negotiable rules** for Laravel security. Violations = vulnerabilities.
+
+## 🔴 Mass Assignment Vulnerability
+
+**ALWAYS define `$fillable` in Models.**
+
+```php
+// ❌ CRITICAL ERROR: No $fillable = mass assignment vulnerability
+class User extends Model
+{
+    // Missing $fillable!
+}
+
+// ❌ DANGEROUS: Using $request->all()
+User::create($request->all());  // Attacker can set is_admin=true
+
+// ✅ CORRECT: Define $fillable explicitly
+class User extends Model
+{
+    protected $fillable = [
+        'name_lastname',
+        'name_firstname',
+        'email',
+        'password',
+    ];
+    
+    // $guarded is alternative but $fillable is preferred (explicit)
+}
+
+// ✅ CORRECT: Use validated data only
+User::create($request->validated());
+```
+
+| Rule                                          | Description                                            |
+| --------------------------------------------- | ------------------------------------------------------ |
+| **Always define `$fillable`**                 | Explicitly list assignable fields                      |
+| **Never use `$request->all()`**               | Use `$request->validated()` or `$request->only([...])` |
+| **Prefer `$fillable` over `$guarded`**        | Whitelist is safer than blacklist                      |
+| **Never put sensitive fields in `$fillable`** | `is_admin`, `role`, `balance` must NOT be fillable     |
+
+---
+
+## 🔴 SQL Injection Prevention
+
+**NEVER use raw user input in queries.**
+
+```php
+// ❌ CRITICAL ERROR: SQL Injection vulnerability
+$email = $request->input('email');
+DB::select("SELECT * FROM users WHERE email = '$email'");  // DANGEROUS!
+
+// ❌ DANGEROUS: String interpolation in whereRaw
+User::whereRaw("email = '$email'")->get();  // DANGEROUS!
+
+// ✅ CORRECT: Use parameter binding
+DB::select("SELECT * FROM users WHERE email = ?", [$email]);
+
+// ✅ CORRECT: Use Query Builder (auto-escapes)
+User::where('email', $email)->get();
+
+// ✅ CORRECT: Parameter binding in whereRaw
+User::whereRaw('email = ?', [$email])->get();
+```
+
+| Rule                             | Description                        |
+| -------------------------------- | ---------------------------------- |
+| **Use Query Builder**            | Eloquent auto-escapes values       |
+| **Use parameter binding**        | `?` placeholders with array values |
+| **Never concatenate user input** | No string interpolation in SQL     |
+| **Validate sort fields**         | Whitelist allowed sort columns     |
+
+```php
+// ✅ CORRECT: Whitelist sort fields to prevent SQL injection
+$allowedSorts = ['id', 'name', 'email', 'created_at'];
+$sortBy = in_array($request->sort_by, $allowedSorts) 
+    ? $request->sort_by 
+    : 'id';
+```
+
+---
+
+## 🔴 XSS Prevention
+
+**Always escape output in Blade templates.**
+
+```php
+// ❌ DANGEROUS: Raw HTML output
+{!! $user->bio !!}  // XSS if bio contains <script>
+
+// ✅ CORRECT: Escaped output (default)
+{{ $user->bio }}  // Auto-escapes HTML entities
+
+// ✅ CORRECT: Only use {!! !!} for trusted HTML
+{!! $trustedHtml !!}  // Only for admin-generated content
+```
+
+---
+
+## 🔴 CSRF Protection
+
+**Never disable CSRF for web routes.**
+
+```php
+// ❌ DANGEROUS: Disabling CSRF
+// In VerifyCsrfToken middleware
+protected $except = ['*'];  // NEVER do this!
+
+// ✅ CORRECT: CSRF is enabled by default for web routes
+// API routes use Sanctum tokens instead
+```
+
+---
+
+## 🔴 Sensitive Data Exposure
+
+**Hide sensitive fields from JSON responses.**
+
+```php
+// ❌ ERROR: Password exposed in API response
+return response()->json($user);  // Includes password!
+
+// ✅ CORRECT: Use $hidden in Model
+class User extends Model
+{
+    protected $hidden = [
+        'password',
+        'remember_token',
+        'two_factor_secret',
+    ];
+}
+
+// ✅ CORRECT: Use Resource to control output
+class UserResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            // password NOT included
+        ];
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+| ❌ Never Do              | ✅ Always Do                       |
+| ----------------------- | --------------------------------- |
+| `$request->all()`       | `$request->validated()`           |
+| Raw SQL with user input | Query Builder / parameter binding |
+| Missing `$fillable`     | Define `$fillable` explicitly     |
+| Missing `$hidden`       | Hide sensitive fields             |
+| Disable CSRF            | Keep CSRF enabled                 |
+| `{!! $userInput !!}`    | `{{ $userInput }}`                |

package/stubs/ai-guides/claude-workflows/bug-fix.md.stub

@@ -0,0 +1,201 @@
+# Bug Fix Workflow
+
+> Step-by-step guide for fixing bugs.
+
+## Overview
+
+```mermaid
+flowchart LR
+    Reproduce --> Locate --> Fix --> Test --> PR
+```
+
+| Step | Action                | Output                         |
+| ---- | --------------------- | ------------------------------ |
+| 1    | Reproduce the bug     | Clear reproduction steps       |
+| 2    | Locate the cause      | File(s) and line(s) identified |
+| 3    | Write failing test    | Test that reproduces bug       |
+| 4    | Fix the bug           | Code changes                   |
+| 5    | Verify test passes    | `./artisan test`               |
+| 6    | Check for regressions | All tests pass                 |
+| 7    | Create PR             | Pull request                   |
+
+---
+
+## Step 1: Reproduce
+
+Before fixing, confirm you can reproduce:
+
+```bash
+# Check logs
+tail -f backend/storage/logs/laravel.log
+
+# Test the endpoint
+curl -X GET https://api.boilerplate.app/api/users
+```
+
+**Document:**
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Error message/stack trace
+
+---
+
+## Step 2: Locate the Cause
+
+### Common Locations
+
+| Symptom             | Check                            |
+| ------------------- | -------------------------------- |
+| 500 error           | `storage/logs/laravel.log`       |
+| 422 validation      | `*Request.php` rules             |
+| Wrong data returned | `*Resource.php`                  |
+| 404 not found       | `routes/api.php` + model binding |
+| N+1 queries         | Missing `with()` in controller   |
+| Date format wrong   | Missing `->toISOString()`        |
+
+### Debug Commands
+
+```bash
+# Check route exists
+./artisan route:list | grep users
+
+# Check model
+./artisan tinker
+>>> User::find(1)
+```
+
+---
+
+## Step 3: Write Failing Test
+
+**ALWAYS write a test that reproduces the bug first.**
+
+```php
+// tests/Feature/Api/UserControllerTest.php
+
+it('異常: bug #123 - returns 500 when name is null', function () {
+    // This should NOT happen but currently does
+    $response = $this->postJson('/api/users', [
+        'email' => 'test@example.com',
+        'password' => 'password123',
+        // name is missing - should return 422, not 500
+    ]);
+    
+    $response->assertUnprocessable(); // Currently fails with 500
+});
+```
+
+Run test to confirm it fails:
+
+```bash
+./artisan test --filter="bug #123"
+```
+
+---
+
+## Step 4: Fix the Bug
+
+Make the minimal change to fix the issue.
+
+**Don't:**
+- Refactor unrelated code
+- Add features
+- Change coding style
+
+**Do:**
+- Fix only the bug
+- Keep changes focused
+- Follow existing patterns
+
+---
+
+## Step 5: Verify Fix
+
+```bash
+# Run the specific test
+./artisan test --filter="bug #123"
+
+# Run all tests for the affected controller
+./artisan test --filter=UserControllerTest
+
+# Run all tests
+./artisan test
+```
+
+---
+
+## Step 6: Check for Regressions
+
+```bash
+# All backend tests
+./artisan test
+
+# Specific test file
+./artisan test tests/Feature/Api/UserControllerTest.php
+```
+
+---
+
+## Step 7: Create PR
+
+### PR Title Format
+
+```
+fix: [#issue] brief description
+```
+
+Example: `fix: [#123] return 422 instead of 500 when name is missing`
+
+### PR Description
+
+```markdown
+## Bug
+
+[Link to issue or description]
+
+## Root Cause
+
+[Explanation of what caused the bug]
+
+## Fix
+
+[Description of the fix]
+
+## Test
+
+- [ ] Added test that reproduces bug
+- [ ] Test passes after fix
+- [ ] All existing tests pass
+```
+
+---
+
+## Debugging Tips
+
+### Laravel Logs
+
+```php
+// Add temporary logging
+Log::info('Debug', ['user' => $user, 'request' => $request->all()]);
+```
+
+### Database Queries
+
+```php
+// Enable query log
+DB::enableQueryLog();
+
+// ... your code ...
+
+// Dump queries
+dd(DB::getQueryLog());
+```
+
+### Tinker
+
+```bash
+./artisan tinker
+>>> User::where('email', 'test@example.com')->first()
+>>> app(UserService::class)->someMethod()
+```