@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/cursor-rules/laravel-request.mdc.stub

@@ -0,0 +1,112 @@
+---
+description: "Laravel FormRequest rules: OpenAPI schema MUST match schemaRules(), extend OmnifyBase for auto-generated validation, never use $request->all(). Apply when editing Request classes."
+globs: ["{{LARAVEL_BASE}}/Http/Requests/**/*.php"]
+alwaysApply: false
+---
+
+# Request Rules
+
+## Golden Rule: Schema MUST Match Validation Rules
+
+OpenAPI Schema properties MUST match the actual `schemaRules()` fields.
+
+## Before Editing Request
+
+1. **Read `OmnifyBase/*RequestBase.php`** to see actual validation rules
+2. **Compare with `#[OA\Schema]`** properties
+3. **Ensure `required` array matches** required validation rules
+4. **Match constraints** (maxLength, minLength, format)
+
+## Checklist
+
+```php
+// Check OmnifyBase/*StoreRequestBase.php → schemaRules()
+return [
+    'name_lastname' => ['required', 'string', 'max:50'],
+    'name_firstname' => ['required', 'string', 'max:50'],
+    'email' => ['required', 'string', 'max:255', 'unique:users'],
+    'password' => ['required', 'string', 'max:255'],
+];
+
+// #[OA\Schema] MUST match
+#[OA\Schema(
+    schema: 'UserStoreRequest',
+    required: ['name_lastname', 'name_firstname', 'email', 'password'],  // ← Match 'required' rules
+    properties: [
+        new OA\Property(property: 'name_lastname', type: 'string', maxLength: 50),  // ← max:50
+        new OA\Property(property: 'name_firstname', type: 'string', maxLength: 50),
+        new OA\Property(property: 'email', type: 'string', format: 'email', maxLength: 255),
+        new OA\Property(property: 'password', type: 'string', format: 'password', maxLength: 255),
+    ]
+)]
+```
+
+## Mapping Validation Rules to OpenAPI
+
+| Laravel Rule | OpenAPI Property            |
+| ------------ | --------------------------- |
+| `required`   | Add to `required: []` array |
+| `max:50`     | `maxLength: 50`             |
+| `min:8`      | `minLength: 8`              |
+| `email`      | `format: 'email'`           |
+| `string`     | `type: 'string'`            |
+| `integer`    | `type: 'integer'`           |
+| `boolean`    | `type: 'boolean'`           |
+| `nullable`   | `nullable: true`            |
+
+## StoreRequest vs UpdateRequest
+
+| Type             | `required`          | Notes                  |
+| ---------------- | ------------------- | ---------------------- |
+| `*StoreRequest`  | All required fields | Creating new resource  |
+| `*UpdateRequest` | Empty or partial    | Partial update allowed |
+
+```php
+// StoreRequest - all fields required
+#[OA\Schema(
+    schema: 'UserStoreRequest',
+    required: ['name_lastname', 'name_firstname', 'email', 'password'],
+    ...
+)]
+
+// UpdateRequest - no required (partial update)
+#[OA\Schema(
+    schema: 'UserUpdateRequest',
+    // No 'required' array - all fields optional
+    properties: [...]
+)]
+```
+
+## Common Mistakes
+
+| Mistake                 | Fix                                  |
+| ----------------------- | ------------------------------------ |
+| Missing field in schema | Check *RequestBase.php schemaRules() |
+| Wrong maxLength         | Match `max:X` rule                   |
+| Missing required        | Check if rule has `required`         |
+| Extra field in schema   | Remove if not in rules               |
+
+## Custom Rules in Child Class
+
+If you override rules in the child Request class, update schema accordingly:
+
+```php
+// UserStoreRequest.php
+public function rules(): array
+{
+    return array_merge($this->schemaRules(), [
+        'email' => ['required', 'string', 'email', 'max:255', 'unique:users'],  // Added 'email' format
+        'password' => ['required', 'string', 'min:8', 'max:255'],  // Added min:8
+    ]);
+}
+
+// Update schema to match
+new OA\Property(property: 'email', type: 'string', format: 'email'),  // ← Added format
+new OA\Property(property: 'password', type: 'string', minLength: 8),  // ← Added minLength
+```
+
+## After Editing
+
+```bash
+./artisan l5-swagger:generate
+```

package/dist/knowledge/cursor-rules/laravel-resource.mdc.stub

@@ -0,0 +1,73 @@
+---
+description: "Laravel API Resource rules: OpenAPI schema MUST match toArray() output, extend OmnifyBase for auto-generated fields, use whenLoaded() for relations. Apply when editing Resource classes."
+globs: ["{{LARAVEL_BASE}}/Http/Resources/**/*.php"]
+alwaysApply: false
+---
+
+# Resource Rules
+
+## Golden Rule: Schema MUST Match Output
+
+OpenAPI Schema properties MUST match the actual `toArray()` / `schemaArray()` output.
+
+## Before Editing Resource
+
+1. **Read `OmnifyBase/*ResourceBase.php`** to see actual fields
+2. **Compare with `#[OA\Schema]`** properties
+3. **Add missing fields** to schema
+4. **Remove non-existent fields** from schema
+
+## Checklist
+
+```php
+// Check OmnifyBase/*ResourceBase.php → schemaArray()
+return [
+    'id' => $this->id,
+    'name_lastname' => $this->name_lastname,
+    'name_full_name' => $this->name_full_name,      // ← Computed field!
+    'email' => $this->email,
+    'created_at' => $this->created_at?->toISOString(),
+];
+
+// #[OA\Schema] MUST have ALL these properties
+#[OA\Schema(
+    properties: [
+        new OA\Property(property: 'id', ...),
+        new OA\Property(property: 'name_lastname', ...),
+        new OA\Property(property: 'name_full_name', ...),  // ← Don't forget!
+        new OA\Property(property: 'email', ...),
+        new OA\Property(property: 'created_at', ...),
+    ]
+)]
+```
+
+## Common Mistakes
+
+| Mistake                                  | Fix                     |
+| ---------------------------------------- | ----------------------- |
+| Missing computed fields (name_full_name) | Check *ResourceBase.php |
+| Schema has field not in output           | Remove from schema      |
+| Field type mismatch                      | Match actual PHP type   |
+| Missing nullable                         | Check if `?->` used     |
+
+## JapaneseName Type Fields
+
+JapaneseName expands to multiple fields including computed ones:
+
+```php
+// All these come from JapaneseName type
+'name_lastname' => $this->name_lastname,
+'name_firstname' => $this->name_firstname,
+'name_kana_lastname' => $this->name_kana_lastname,
+'name_kana_firstname' => $this->name_kana_firstname,
+'name_full_name' => $this->name_full_name,           // Computed!
+'name_full_name_kana' => $this->name_full_name_kana, // Computed!
+```
+
+**MUST include ALL in OpenAPI Schema!**
+
+## After Editing
+
+```bash
+./artisan l5-swagger:generate
+```

package/dist/knowledge/cursor-rules/laravel-review.mdc.stub

@@ -0,0 +1,69 @@
+---
+description: "Code review checklist for Laravel: security ($request->validated, SQL injection), performance (eager loading, N+1), and quality standards. Mention @laravel-review in chat to invoke."
+globs: []
+alwaysApply: false
+---
+
+# Code Review Rules
+
+> Review process for Laravel code
+
+## Review Process
+
+1. Security Check → 2. Performance Check → 3. Quality Check → 4. Test Check
+
+## Security Checklist
+
+| Check           | Look For                     |
+| --------------- | ---------------------------- |
+| Mass Assignment | `$request->validated()`      |
+| SQL Injection   | No raw SQL                   |
+| `$fillable`     | Defined, no sensitive fields |
+| `$hidden`       | Password hidden              |
+
+## Performance Checklist
+
+| Check      | Look For               |
+| ---------- | ---------------------- |
+| N+1        | `with()` for relations |
+| Pagination | `paginate()` for lists |
+| Resources  | `whenLoaded()`         |
+
+## Quality Checklist
+
+| Check      | Look For        |
+| ---------- | --------------- |
+| Validation | FormRequest     |
+| Response   | Resource        |
+| Dates      | `toISOString()` |
+
+## Code Style Checklist
+
+| Check       | Look For                               |
+| ----------- | -------------------------------------- |
+| **Imports** | No FQCN inline (`\Full\Path\Class`)    |
+| Use         | All classes imported with `use` at top |
+| Naming      | Follows conventions                    |
+
+## Test Checklist
+
+| Endpoint | 正常系 | 異常系   |
+| -------- | ------ | -------- |
+| store    | 201    | 422      |
+| show     | 200    | 404      |
+| update   | 200    | 404, 422 |
+| destroy  | 204    | 404      |
+
+## Output Format
+
+```markdown
+## Security
+✅ Using `$request->validated()`
+❌ Missing `$hidden` for password
+
+## Performance
+✅ Eager loading
+❌ Missing pagination
+
+## Recommendation: Request Changes
+```

package/dist/knowledge/cursor-rules/laravel-testing.mdc.stub

@@ -0,0 +1,138 @@
+---
+description: "PEST testing guide: 正常系 (happy path) + 異常系 (error cases), Japanese naming conventions, RefreshDatabase trait, and factory usage. Apply when writing or reviewing tests."
+globs: ["{{LARAVEL_ROOT}}tests/**/*.php"]
+alwaysApply: false
+---
+
+# Testing Rules (PEST)
+
+> **Agent:** Act as **@tester** agent
+> - Read `.claude/omnify/guides/laravel/testing.md` for full guide
+
+## How to Run Tests
+
+```bash
+# Run ALL tests (from project root - uses Docker wrapper)
+./artisan test
+
+# Run specific test file
+./artisan test --filter=UserControllerTest
+
+# Run specific test method
+./artisan test --filter="creates user with valid data"
+
+# Run with coverage (if xdebug installed)
+./artisan test --coverage
+```
+
+> **Note:** The root `./artisan` script is a wrapper that runs commands inside Docker container.
+
+## Testing Process
+
+1. **Before writing tests:**
+   - Read the Controller to understand endpoints
+   - Read the Request to understand validation rules
+   - Read the Resource to understand response structure
+
+2. **Write tests covering:**
+   - 正常系 (Normal cases) - success scenarios
+   - 異常系 (Abnormal cases) - failure scenarios
+
+3. **Run tests to verify:**
+   ```bash
+   cd backend && ./artisan test
+   ```
+
+4. **All tests must pass before committing**
+
+## Critical Rules
+
+1. **PEST Syntax** - Use `describe()` + `it()`, not PHPUnit
+2. **正常系 + 異常系** - Cover both success and failure
+3. **Naming** - Use `正常:` and `異常:` prefixes
+4. **Coverage** - All endpoints, all validation rules
+5. **RefreshDatabase** - MUST use for SQLite in-memory
+
+## Database Trait - IMPORTANT
+
+```php
+// ✅ CORRECT - Use RefreshDatabase for SQLite in-memory
+use Illuminate\Foundation\Testing\RefreshDatabase;
+uses(RefreshDatabase::class);
+
+// ❌ WRONG - DatabaseTransactions doesn't run migrations
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+uses(DatabaseTransactions::class);  // Will fail with "no such table"
+```
+
+| Trait                  | When to Use                       | Notes                           |
+| ---------------------- | --------------------------------- | ------------------------------- |
+| `RefreshDatabase`      | SQLite in-memory (default)        | Runs migrations, then truncates |
+| `DatabaseTransactions` | MySQL/PostgreSQL with existing DB | Only wraps in transaction       |
+
+## Test Naming
+
+```php
+// 正常系 (Normal) - success behavior
+it('正常: returns paginated users')
+it('正常: creates user with valid data')
+it('正常: deletes user')
+
+// 異常系 (Abnormal) - failure behavior
+it('異常: fails to create user with missing email')
+it('異常: fails to create user with invalid kana format')
+it('異常: returns 404 when user not found')
+it('異常: returns 401 when not authenticated')
+```
+
+## Coverage Matrix
+
+| Endpoint | 正常系             | 異常系                |
+| -------- | ------------------ | --------------------- |
+| index    | List, filter, sort | Empty, invalid params |
+| store    | Creates → 201      | 422 (each field)      |
+| show     | Returns → 200      | 404                   |
+| update   | Updates → 200      | 404, 422              |
+| destroy  | Deletes → 204      | 404                   |
+
+## Template
+
+```php
+describe('POST /api/users', function () {
+    // 正常系
+    it('正常: creates user with valid data', function () {
+        $response = $this->postJson('/api/users', validUserData());
+        
+        $response->assertCreated();
+        $this->assertDatabaseHas('users', ['email' => 'test@example.com']);
+    });
+    
+    // 異常系 - Required fields
+    it('異常: fails to create user with missing email', function () {
+        $data = validUserData();
+        unset($data['email']);
+        
+        $this->postJson('/api/users', $data)
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors(['email']);
+    });
+    
+    // 異常系 - Format validation
+    it('異常: fails to create user with invalid email format', function () {
+        $this->postJson('/api/users', validUserData(['email' => 'invalid']))
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors(['email']);
+    });
+});
+```
+
+## Japanese Field Tests
+
+```php
+it('異常: fails with hiragana in kana field', function () {
+    $this->postJson('/api/users', validUserData([
+        'name_kana_lastname' => 'たなか'  // hiragana - should fail
+    ]))->assertUnprocessable()
+       ->assertJsonValidationErrors(['name_kana_lastname']);
+});
+```

package/dist/knowledge/cursor-rules/laravel.mdc.stub

@@ -0,0 +1,138 @@
+---
+description: "Laravel backend rules for Omnify projects: schema-first migrations, thin controllers, security patterns, and code generation. Apply when working with Laravel controllers, models, migrations, or API endpoints."
+globs: ["{{LARAVEL_BASE}}/**/*.php"]
+alwaysApply: false
+---
+
+# Laravel Rules
+
+> **Documentation:** `.claude/omnify/guides/laravel/`
+> **Team Migration Guide:** `.claude/omnify/guides/laravel/migrations-team.md`
+> **Specific Rules:** See also `laravel-controller.mdc`, `laravel-resource.mdc`, `laravel-request.mdc`, `laravel-testing.mdc`, `migrations-workflow.mdc`, `omnify-migrations.mdc`
+
+## ⛔ CRITICAL: DO NOT EDIT
+
+| Path | Reason |
+|------|--------|
+| `{{LARAVEL_ROOT}}database/migrations/omnify/**` | Auto-generated by Omnify - will be overwritten! |
+| `{{LARAVEL_BASE}}/Models/OmnifyBase/**` | Auto-generated base models |
+| `{{LARAVEL_BASE}}/Http/Requests/OmnifyBase/**` | Auto-generated request bases |
+| `{{LARAVEL_BASE}}/Http/Resources/OmnifyBase/**` | Auto-generated resource bases |
+
+**To modify schema:** Edit YAML in `schemas/` → run `npx omnify generate`
+
+---
+
+## Critical Rules
+
+1. **Thin Controller** - Validate → Delegate → Respond (see `laravel-controller.mdc`)
+2. **🚨 Schema-First** - **NEVER** run `php artisan make:migration`! Use Omnify schemas instead (see `migrations-workflow.mdc`)
+3. **Security** - Always use `$request->validated()`, never `$request->all()`
+4. **Performance** - Use `with()` for relations, `paginate()` for lists
+5. **Dates** - Store UTC, return `->toISOString()`
+6. **Testing** - Write 正常系 + 異常系 tests (see `laravel-testing.mdc`)
+7. **Imports** - Always `use` and short class names, never FQCN inline
+8. **OpenAPI Paths** - NO `/api` prefix! `api.php` already has it (see `laravel-controller.mdc`)
+
+## ⛔ FORBIDDEN: Manual Migrations
+
+```bash
+# ❌ NEVER DO THIS
+php artisan make:migration create_xxx_table
+php artisan make:migration add_xxx_to_xxx_table
+
+# ✅ ALWAYS DO THIS
+# 1. Edit/Create YAML schema in schemas/
+# 2. Run: npx omnify generate
+# 3. Run: php artisan migrate
+```
+
+See `migrations-workflow.mdc` for complete guide.
+
+## File-Specific Rules
+
+| File Type  | Rule File               | Key Focus                    |
+| ---------- | ----------------------- | ---------------------------- |
+| Controller | `laravel-controller.mdc` | Thin, Query Builder, OpenAPI |
+| Resource   | `laravel-resource.mdc`   | Schema matches output        |
+| Request    | `laravel-request.mdc`    | Schema matches validation    |
+| Test       | `laravel-testing.mdc`    | 正常系 + 異常系 coverage     |
+
+## Security Checklist
+
+- [ ] `$fillable` defined in Model
+- [ ] `$hidden` for sensitive fields
+- [ ] `$request->validated()` not `$request->all()`
+- [ ] No raw SQL with user input
+- [ ] `with()` for eager loading
+- [ ] `whenLoaded()` in Resources
+- [ ] `paginate()` for list endpoints
+
+## When to Use What
+
+| Scenario         | Solution           |
+| ---------------- | ------------------ |
+| Simple CRUD      | Controller + Model |
+| Multi-step logic | Service            |
+| Reusable action  | Action class       |
+| Async task       | Job                |
+
+## Authentication Models
+
+When `authenticatable: true` is set in schema, model extends `Authenticatable`:
+
+```yaml
+# schemas/auth/User.yaml
+options:
+  authenticatable: true
+  authenticatableLoginIdField: email
+  authenticatablePasswordField: password
+  authenticatableGuardName: web  # Optional: for multi-guard
+```
+
+**Required `config/auth.php` for custom guards:**
+
+```php
+'guards' => [
+    'admin' => ['driver' => 'session', 'provider' => 'admins'],
+],
+'providers' => [
+    'admins' => ['driver' => 'eloquent', 'model' => App\Models\Admin::class],
+],
+```
+
+**See:** `.claude/omnify/guides/omnify/schema-guide.md` → "Authenticatable Option - Detailed Guide"
+
+## Pre-Edit Checklist
+
+**BEFORE editing any file, MUST:**
+
+1. **Read the file first** - Check existing imports, patterns, style
+2. **Check imports** - Add `use` if class not imported
+3. **Follow existing style** - Match indentation, naming, patterns
+4. **Never use FQCN inline** - Always import first
+
+## Imports Rule
+
+```php
+// ❌ WRONG: Inline FQCN
+public function store(): \Illuminate\Http\JsonResponse
+
+// ✅ CORRECT: Import and use short name
+use Illuminate\Http\JsonResponse;
+public function store(): JsonResponse
+```
+
+## Don't Over-Engineer
+
+| ❌ DON'T                             | ✅ DO                      |
+| ----------------------------------- | ------------------------- |
+| Add workaround to hide bugs         | Fix root cause or report  |
+| Repository for simple CRUD          | Use Eloquent directly     |
+| Service that just wraps Model       | Controller + Model        |
+| Interface with 1 implementation     | Concrete class            |
+| Manual 404 check with route binding | Trust framework           |
+| "Improve" unrelated code            | Change only what's needed |
+| Build for future "just in case"     | YAGNI - build when needed |
+
+**Full examples:** `.claude/omnify/guides/laravel/architecture.md`