@famgia/omnify-laravel 0.0.106 → 0.0.108

package/dist/plugin.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-laravel",
-  "version": "0.0.106",
+  "version": "0.0.108",
   "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.95",
-    "@famgia/omnify-core": "0.0.97",
-    "@famgia/omnify-atlas": "0.0.91"
+    "@famgia/omnify-types": "0.0.97",
+    "@famgia/omnify-core": "0.0.99",
+    "@famgia/omnify-atlas": "0.0.93"
   },
   "scripts": {
     "build": "tsup",

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

@@ -6,6 +6,20 @@ alwaysApply: false
 
 # Controller Rules
 
+## ⚠️ CRITICAL: OpenAPI Route Prefix
+
+**NEVER include `/api` in OpenAPI paths!** Laravel's `api.php` already has this prefix.
+
+```php
+// ❌ CRITICAL BUG - Results in /api/api/users !!
+#[OA\Get(path: '/api/users')]
+
+// ✅ CORRECT - api.php already adds /api prefix
+#[OA\Get(path: '/users')]
+```
+
+---
+
 ## 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,43 @@
 
 > **Related:** [README](./README.md) | [Controller Guide](./controller-guide.md) | [Checklist](./checklist.md)
 
+## ⚠️ CRITICAL: Route Prefix Warning
+
+**DO NOT duplicate the `/api` prefix in OpenAPI paths!**
+
+Laravel's `routes/api.php` already has `/api` prefix applied automatically. If you write `/api/users` in OpenAPI, it becomes `/api/api/users` - a serious bug!
+
+```php
+// ❌ CRITICAL BUG - NEVER DO THIS!
+#[OA\Get(path: '/api/users')]  // Results in: /api/api/users !!
+
+// ✅ CORRECT - Routes file already has /api prefix
+#[OA\Get(path: '/users')]  // Results in: /api/users
+```
+
+**Remember:** The `api.php` file is loaded under the `/api` prefix by Laravel's RouteServiceProvider. You only need to write the path AFTER `/api`.
+
+| Routes File  | OpenAPI Path  | Actual URL     |
+|--------------|---------------|----------------|
+| `api.php`    | `/users`      | `/api/users`   |
+| `api.php`    | `/users/{id}` | `/api/users/1` |
+| `web.php`    | `/dashboard`  | `/dashboard`   |
+
+---
+
+## ⚠️ 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 +168,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 +190,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 +218,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 +237,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 +267,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'],