@famgia/omnify-laravel 0.0.107 → 0.0.109

package/dist/plugin.js

@@ -1,6 +1,6 @@
 import {
   laravelPlugin
-} from "./chunk-7YHLXBF5.js";
+} from "./chunk-GDFAEEEG.js";
 export {
   laravelPlugin as default,
   laravelPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-laravel",
-  "version": "0.0.107",
+  "version": "0.0.109",
   "description": "Laravel migration and TypeScript type generator for omnify-schema",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@famgia/omnify-types": "0.0.96",
-    "@famgia/omnify-core": "0.0.98",
-    "@famgia/omnify-atlas": "0.0.92"
+    "@famgia/omnify-types": "0.0.98",
+    "@famgia/omnify-core": "0.0.100",
+    "@famgia/omnify-atlas": "0.0.94"
   },
   "scripts": {
     "build": "tsup",

package/stubs/ai-guides/cursor/laravel-controller.mdc.stub

@@ -6,6 +6,36 @@ alwaysApply: false
 
 # Controller Rules
 
+## ⚠️ CRITICAL: Check Route Prefix BEFORE Writing OpenAPI
+
+**MUST check route file prefix first!** Don't assume - VERIFY.
+
+### Before Writing OpenAPI Path:
+
+1. **Check route file** → Which file has your route? (`api.php`, `web.php`, custom?)
+2. **Check prefix** → Look in `RouteServiceProvider` or `bootstrap/app.php`
+3. **Write path WITHOUT prefix** → OpenAPI path = Route definition path
+
+```php
+// Route trong api.php (prefix: /api)
+Route::get('/users', [UserController::class, 'index']);
+
+// ❌ SAI - Duplicate prefix → /api/api/users !!
+#[OA\Get(path: '/api/users')]
+
+// ✅ ĐÚNG - Path không có prefix
+#[OA\Get(path: '/users')]  // → /api/users
+```
+
+| Route File | Prefix | Route Definition | OpenAPI Path |
+|------------|--------|------------------|--------------|
+| `api.php` | `/api` | `/users` | `/users` |
+| `web.php` | (none) | `/dashboard` | `/dashboard` |
+
+**Full guide:** `.claude/guides/laravel/openapi.md`
+
+---
+
 ## Golden Rule: Thin Controller
 
 ```php

package/stubs/ai-guides/cursor/laravel.mdc.stub

@@ -7,7 +7,20 @@ alwaysApply: false
 # Laravel Rules
 
 > **Documentation:** `.claude/guides/laravel/`
-> **Specific Rules:** See also `laravel-controller.mdc`, `laravel-resource.mdc`, `laravel-request.mdc`, `laravel-testing.mdc`
+> **Specific Rules:** See also `laravel-controller.mdc`, `laravel-resource.mdc`, `laravel-request.mdc`, `laravel-testing.mdc`, `omnify-migrations.mdc`
+
+## ⛔ CRITICAL: DO NOT EDIT
+
+| Path | Reason |
+|------|--------|
+| `database/migrations/omnify/**` | Auto-generated by Omnify - will be overwritten! |
+| `app/Models/OmnifyBase/**` | Auto-generated base models |
+| `app/Http/Requests/OmnifyBase/**` | Auto-generated request bases |
+| `app/Http/Resources/OmnifyBase/**` | Auto-generated resource bases |
+
+**To modify schema:** Edit YAML in `schemas/` → run `npx omnify generate`
+
+---
 
 ## Critical Rules
 
@@ -18,6 +31,7 @@ alwaysApply: false
 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`)
 
 ## File-Specific Rules
 

package/stubs/ai-guides/cursor/omnify-migrations.mdc.stub

@@ -0,0 +1,109 @@
+---
+description: "CRITICAL: Auto-generated Omnify migrations - DO NOT EDIT"
+globs: ["{{LARAVEL_BASE}}/migrations/omnify/**"]
+alwaysApply: true
+---
+
+# ⛔ CRITICAL: DO NOT EDIT OMNIFY MIGRATIONS
+
+## These files are AUTO-GENERATED
+
+All files in `database/migrations/omnify/` are automatically generated by Omnify.
+
+**ANY MANUAL CHANGES WILL BE OVERWRITTEN** when running `npx omnify generate`.
+
+---
+
+## ❌ ABSOLUTELY FORBIDDEN
+
+```php
+// NEVER modify files in database/migrations/omnify/
+// Even "simple fixes" will be lost!
+```
+
+| Action | Result |
+|--------|--------|
+| Add column manually | ❌ Overwritten on next generate |
+| Modify column type | ❌ Overwritten on next generate |
+| Add index manually | ❌ Overwritten on next generate |
+| Fix "typo" | ❌ Overwritten on next generate |
+
+---
+
+## ✅ CORRECT APPROACH
+
+### 1. Edit the YAML Schema
+
+```yaml
+# schemas/auth/User.yaml
+properties:
+  # Add or modify properties HERE
+  new_field:
+    type: String
+    length: 100
+```
+
+### 2. Regenerate Migrations
+
+```bash
+npx omnify generate
+php artisan migrate
+```
+
+---
+
+## Need Custom Migration?
+
+For changes NOT supported by Omnify schemas:
+
+1. Create migration **OUTSIDE** the `omnify/` folder:
+
+```bash
+php artisan make:migration add_custom_field_to_users_table
+# Creates: database/migrations/2026_01_12_000000_add_custom_field_to_users_table.php
+# This is SAFE - Omnify won't touch it
+```
+
+2. Keep the omnify/ folder untouched
+
+---
+
+## Folder Structure
+
+```
+database/migrations/
+├── omnify/                    ← ⛔ AUTO-GENERATED - DO NOT EDIT
+│   ├── 2026_01_01_000000_create_users_table.php
+│   ├── 2026_01_01_000001_create_posts_table.php
+│   └── ...
+├── 2026_01_12_120000_add_custom_field.php  ← ✅ Safe to edit
+└── 2026_01_12_130000_custom_migration.php  ← ✅ Safe to edit
+```
+
+---
+
+## Quick Reference
+
+| Want to... | Do this |
+|------------|---------|
+| Add column | Edit schema YAML → `npx omnify generate` |
+| Modify column | Edit schema YAML → `npx omnify generate` |
+| Add index | Edit schema YAML → `npx omnify generate` |
+| Custom migration | `php artisan make:migration` (outside omnify/) |
+| Fix generation bug | Report issue or edit Omnify plugin |
+
+---
+
+## If You See This Warning
+
+If a file has this header:
+
+```php
+/**
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ * ...
+ */
+```
+
+**STOP!** Do not edit this file. Edit the schema YAML instead.

package/stubs/ai-guides/laravel/openapi.md.stub

@@ -2,6 +2,86 @@
 
 > **Related:** [README](./README.md) | [Controller Guide](./controller-guide.md) | [Checklist](./checklist.md)
 
+## ⚠️ CRITICAL: Check Route Prefix BEFORE Writing OpenAPI Path
+
+### Step 1: Check Which Route File the Controller Uses
+
+```bash
+# Find where your route is registered
+grep -r "UserController" routes/
+```
+
+### Step 2: Check the Route Prefix in That File
+
+```php
+// bootstrap/app.php hoặc app/Providers/RouteServiceProvider.php
+// Tìm xem route file có prefix gì
+
+// Ví dụ Laravel 11+: bootstrap/app.php
+->withRouting(
+    api: __DIR__.'/../routes/api.php',    // ← /api prefix tự động!
+    web: __DIR__.'/../routes/web.php',
+    apiPrefix: 'api',                      // ← Đây là prefix!
+)
+
+// Ví dụ Laravel 10: app/Providers/RouteServiceProvider.php
+Route::middleware('api')
+    ->prefix('api')                        // ← Đây là prefix!
+    ->group(base_path('routes/api.php'));
+```
+
+### Step 3: Write OpenAPI Path = Actual Route Path (KHÔNG có prefix)
+
+| Route File | Route Definition | Prefix | OpenAPI Path | Final URL |
+|------------|------------------|--------|--------------|-----------|
+| `api.php` | `Route::get('/users', ...)` | `/api` | `path: '/users'` | `/api/users` |
+| `api.php` | `Route::get('/users/{id}', ...)` | `/api` | `path: '/users/{id}'` | `/api/users/1` |
+| `web.php` | `Route::get('/dashboard', ...)` | (none) | `path: '/dashboard'` | `/dashboard` |
+| `admin.php` | `Route::get('/stats', ...)` | `/admin/api` | `path: '/stats'` | `/admin/api/stats` |
+
+### ❌ CRITICAL BUG - Duplicate Prefix
+
+```php
+// Route trong api.php (đã có prefix /api)
+Route::get('/users', [UserController::class, 'index']);
+
+// ❌ SAI - Viết thêm /api vào path
+#[OA\Get(path: '/api/users')]  // → /api/api/users !!
+
+// ✅ ĐÚNG - Chỉ viết path sau prefix
+#[OA\Get(path: '/users')]  // → /api/users ✓
+```
+
+### Quick Reference: Common Prefixes
+
+| Route File | Default Prefix | OpenAPI Server URL |
+|------------|----------------|-------------------|
+| `api.php` | `/api` | `#[OA\Server(url: '/api')]` |
+| `web.php` | (none) | `#[OA\Server(url: '/')]` |
+| Custom | Check RouteServiceProvider | Match the prefix |
+
+### Checklist Before Writing OpenAPI
+
+- [ ] Check route file (`api.php` / `web.php` / custom)
+- [ ] Check prefix in `RouteServiceProvider` or `bootstrap/app.php`
+- [ ] OpenAPI path = Route path (WITHOUT prefix)
+- [ ] `#[OA\Server(url: ...)]` matches the prefix
+
+---
+
+## ⚠️ CRITICAL: L5-Swagger Configuration
+
+**MUST set `use_absolute_path` to `false`** in `config/l5-swagger.php`:
+
+```php
+// config/l5-swagger.php
+'use_absolute_path' => env('L5_SWAGGER_USE_ABSOLUTE_PATH', false),
+```
+
+Without this, Swagger UI will fail to load the API documentation correctly.
+
+---
+
 ## Overview
 
 This project uses [L5-Swagger](https://github.com/DarkaOnLine/L5-Swagger) with PHP 8 Attributes.
@@ -131,7 +211,7 @@ class Schemas
 
 ```php
 #[OA\Get(
-    path: '/api/users',
+    path: '/users',           // ⚠️ NO /api prefix! api.php already has it
     summary: 'List users',
     description: 'Paginated list with search and sorting',
     tags: ['Users'],
@@ -153,7 +233,7 @@ public function index(Request $request): AnonymousResourceCollection
 
 ```php
 #[OA\Post(
-    path: '/api/users',
+    path: '/users',           // ⚠️ NO /api prefix!
     summary: 'Create user',
     description: 'Create a new user account',
     tags: ['Users'],
@@ -181,7 +261,7 @@ public function store(UserStoreRequest $request): UserResource
 
 ```php
 #[OA\Get(
-    path: '/api/users/{id}',
+    path: '/users/{id}',      // ⚠️ NO /api prefix!
     summary: 'Get user',
     description: 'Get user by ID',
     tags: ['Users'],
@@ -200,7 +280,7 @@ public function show(User $user): UserResource
 
 ```php
 #[OA\Put(
-    path: '/api/users/{id}',
+    path: '/users/{id}',      // ⚠️ NO /api prefix!
     summary: 'Update user',
     description: 'Update user (partial update supported)',
     tags: ['Users'],
@@ -230,7 +310,7 @@ public function update(UserUpdateRequest $request, User $user): UserResource
 
 ```php
 #[OA\Delete(
-    path: '/api/users/{id}',
+    path: '/users/{id}',      // ⚠️ NO /api prefix!
     summary: 'Delete user',
     description: 'Permanently delete user',
     tags: ['Users'],