@famgia/omnify-laravel 0.0.88 → 0.0.90

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()
+```

package/stubs/ai-guides/claude-workflows/code-review.md.stub

@@ -0,0 +1,164 @@
+# Code Review Workflow
+
+> Checklist for reviewing pull requests.
+
+## Overview
+
+```mermaid
+flowchart LR
+    Read --> Security --> Performance --> Quality --> Test --> Approve
+```
+
+---
+
+## 1. Understand the Change
+
+- [ ] Read PR description
+- [ ] Understand the purpose
+- [ ] Check linked issue/ticket
+
+---
+
+## 2. Security Review
+
+> **Reference:** [/rules/security.md](../rules/security.md)
+
+### Must Check
+
+| Item            | Look For                                            |
+| --------------- | --------------------------------------------------- |
+| Mass Assignment | Using `$request->validated()` not `$request->all()` |
+| SQL Injection   | No raw SQL with user input                          |
+| `$fillable`     | Defined in models, no sensitive fields              |
+| `$hidden`       | Password and tokens hidden                          |
+| XSS             | No `{!! $userInput !!}` in Blade                    |
+
+### Code Review
+
+```php
+// ❌ REJECT: Mass assignment vulnerability
+User::create($request->all());
+
+// ✅ APPROVE: Using validated data
+User::create($request->validated());
+```
+
+---
+
+## 3. Performance Review
+
+> **Reference:** [/rules/performance.md](../rules/performance.md)
+
+### Must Check
+
+| Item          | Look For                         |
+| ------------- | -------------------------------- |
+| N+1 Queries   | `with()` used for relationships  |
+| Pagination    | List endpoints use `paginate()`  |
+| Resources     | `whenLoaded()` for relationships |
+| Eager Loading | No lazy loading in loops         |
+
+### Code Review
+
+```php
+// ❌ REJECT: N+1 problem
+$posts = Post::all();
+foreach ($posts as $post) {
+    echo $post->author->name;
+}
+
+// ✅ APPROVE: Eager loaded
+$posts = Post::with('author')->get();
+```
+
+---
+
+## 4. Code Quality Review
+
+### Must Check
+
+| Item          | Look For                           |
+| ------------- | ---------------------------------- |
+| Validation    | FormRequest not inline validation  |
+| Response      | Resource not raw model             |
+| Route binding | `User $user` not `findOrFail($id)` |
+| Dates         | `->toISOString()` in Resources     |
+| Types         | Return type hints on methods       |
+
+### Naming
+
+> **Reference:** [/rules/naming.md](../rules/naming.md)
+
+| Type       | Pattern                  |
+| ---------- | ------------------------ |
+| Controller | `{Model}Controller`      |
+| Request    | `{Model}{Action}Request` |
+| Resource   | `{Model}Resource`        |
+| Test       | `{Model}ControllerTest`  |
+
+---
+
+## 5. Test Review
+
+### Must Have
+
+| Endpoint | 正常系             | 異常系                |
+| -------- | ------------------ | --------------------- |
+| index    | List, filter, sort | Empty, invalid params |
+| store    | Creates → 201      | 422 (validation)      |
+| show     | Returns → 200      | 404                   |
+| update   | Updates → 200      | 404, 422              |
+| destroy  | Deletes → 204      | 404                   |
+
+### Test Naming
+
+```php
+// ✅ Good naming
+it('正常: creates user with valid data')
+it('異常: fails to create user with invalid email')
+it('異常: returns 404 when user not found')
+```
+
+---
+
+## 6. Final Checks
+
+- [ ] All tests pass
+- [ ] No debug code (`dd()`, `dump()`, `Log::debug()`)
+- [ ] No commented-out code
+- [ ] No console.log or debug statements
+- [ ] Follows existing patterns in codebase
+
+---
+
+## Review Decision
+
+### ✅ Approve If
+
+- All security checks pass
+- All performance checks pass
+- Tests cover 正常系 + 異常系
+- Code follows conventions
+
+### 🔄 Request Changes If
+
+- Security vulnerability found
+- Performance issue (N+1, no pagination)
+- Missing tests
+- Naming/pattern violations
+
+### Example Comments
+
+```markdown
+## Security Issue
+❌ Line 45: Using `$request->all()` - please use `$request->validated()`
+
+## Performance Issue
+❌ Line 23: Missing `with('author')` - will cause N+1 queries
+
+## Missing Test
+❌ No test for 422 validation error case
+
+## Naming
+❌ `UserCreateRequest` should be `UserStoreRequest` (Laravel convention)
+```