@famgia/omnify-ai-guides 2.0.15

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

@@ -0,0 +1,336 @@
+---
+description: "React + Ant Design + TanStack Query rules for Omnify projects: component patterns, form validation with Zod, i18n, service layer, and generated types. Apply when creating React components, forms, or API integrations."
+globs: ["{{TYPESCRIPT_BASE}}/**/*.{ts,tsx}"]
+alwaysApply: false
+---
+
+# React + Ant Design Rules
+
+> **Related Rules:**
+> - **Form Development:** `.cursor/rules/omnify/react-form.mdc`
+> - **Design System:** `.cursor/rules/omnify/react-design.mdc`
+> - **Services:** `.cursor/rules/omnify/react-services.mdc`
+> - **Schema Creation:** `.cursor/rules/omnify/schema-create.mdc` (mention `@schema-create` in chat)
+
+## Guide Documentation
+
+- Read `.claude/omnify/guides/react/` for patterns
+
+## Critical Rules
+
+1. **Use Ant Design** - Don't recreate existing components
+2. **Use Omnify types** - Import from `@omnify/schemas`, don't duplicate
+3. **Use i18n** - Use `useTranslations()` for UI text
+4. **Service Layer** - API calls in `services/`, not components
+5. **TanStack Query** - For all server state, no `useState` + `useEffect`
+
+## Quick Patterns
+
+### Service
+
+```typescript
+export const userService = {
+  list: (params?: UserListParams) => api.get("/api/users", { params }).then(r => r.data),
+  create: (input: UserCreate) => api.post("/api/users", input).then(r => r.data.data),
+};
+```
+
+### Query
+
+```typescript
+const { data, isLoading } = useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => userService.list(filters),
+});
+```
+
+### Mutation
+
+```typescript
+const mutation = useMutation({
+  mutationFn: userService.create,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+    message.success(t("messages.created"));
+  },
+  onError: (error) => form.setFields(getFormErrors(error)),
+});
+```
+
+## Types Rule
+
+```typescript
+// ✅ Use Omnify-generated types
+import type { User, UserCreate } from "@omnify/schemas";
+
+// ✅ Only define query params locally
+export interface UserListParams { ... }
+
+// ❌ Don't redefine Omnify types
+export interface UserCreateInput { ... }  // WRONG
+```
+
+## ⚠️ Enum Usage Rules (CRITICAL)
+
+**ALWAYS use generated Enums** - NEVER inline union types or type extractions!
+
+### ❌ BAD Patterns (FORBIDDEN)
+
+```typescript
+// ❌ Complex type extraction - FORBIDDEN!
+newFilter.approval_status = status as NonNullable<ListParams["filter"]>["approval_status"];
+
+// ❌ Hardcoded union type - NOT DRY!
+newFilter.approval_status = status as "pending" | "approved" | "rejected";
+
+// ❌ Using string type - NO TYPE SAFETY!
+const [status, setStatus] = useState<string>("");
+
+// ❌ Hardcoded comparisons
+if (status === "pending") { ... }
+```
+
+### ✅ GOOD Patterns (REQUIRED)
+
+```typescript
+// ✅ Import Enum from generated file
+import { 
+  PostStatus, 
+  PostStatusValues,
+  isPostStatus,
+  getPostStatusLabel
+} from "@omnify/enum/PostStatus";
+
+// ✅ Type assertions with Enum
+newFilter.approval_status = status as PostStatus;
+
+// ✅ State with Enum type
+const [status, setStatus] = useState<PostStatus | "">(""); 
+// OR with default value:
+const [status, setStatus] = useState<PostStatus>(PostStatus.Pending);
+
+// ✅ Enum comparisons
+if (status === PostStatus.Pending) { ... }
+
+// ✅ Iterate with Values array
+const options = PostStatusValues.map(value => ({
+  value,
+  label: getPostStatusLabel(value, locale)
+}));
+
+// ✅ Type guard for validation
+if (isPostStatus(unknownValue)) {
+  // unknownValue is PostStatus here
+}
+```
+
+### Generated Enum Files Structure
+
+```
+@omnify/enum/
+├── PostStatus.ts
+│   ├── PostStatus        (enum)
+│   ├── PostStatusValues  (array of all values)
+│   ├── isPostStatus()    (type guard)
+│   └── getPostStatusLabel()  (i18n label)
+├── OrderStatus.ts
+└── ...
+```
+
+### Select/Filter Options Pattern
+
+```typescript
+import { PostStatus, PostStatusValues, getPostStatusLabel } from "@omnify/enum/PostStatus";
+
+// ✅ Build options from Enum
+const statusOptions = PostStatusValues.map(value => ({
+  value,
+  label: getPostStatusLabel(value, locale)
+}));
+
+<Select options={statusOptions} />
+```
+
+## Form Pattern (Omnify)
+
+> **Detailed Guide:** See `react-form.mdc` for complete form development guide.
+
+**Quick Reference:**
+
+```typescript
+// 1. Imports
+import { zodRule, setZodLocale } from '@/omnify/lib';
+import { OmnifyForm } from '@/omnify/components';
+import { customerSchemas, customerI18n, getCustomerFieldLabel } from '@/omnify/schemas';
+
+// 2. Helper functions (MUST define in every form)
+const LOCALE = 'ja';
+const label = (key: string) => getCustomerFieldLabel(key, LOCALE);
+const rule = (key: keyof typeof customerSchemas) => zodRule(customerSchemas[key], label(key));
+
+// 3. Form.Item pattern
+<Form.Item name="email" label={label('email')} rules={[rule('email')]}>
+  <Input />
+</Form.Item>
+
+// 4. Japanese compound fields
+<OmnifyForm.JapaneseName schemas={customerSchemas} i18n={customerI18n} prefix="name" />
+<OmnifyForm.JapaneseAddress form={form} schemas={customerSchemas} i18n={customerI18n} prefix="address" />
+```
+
+## File Location
+
+| What                    | Where                                       |
+| ----------------------- | ------------------------------------------- |
+| Component (1 feature)   | `features/{feature}/`                       |
+| Component (2+ features) | `components/common/`                        |
+| Service (API)           | `services/` (ALWAYS)                        |
+| Hook (1 feature)        | `features/{feature}/`                       |
+| Hook (2+ features)      | `hooks/`                                    |
+| Zod Schema              | `schemas/{model}.ts`                        |
+| Validation utils        | `lib/form-validation.ts`, `lib/zod-i18n.ts` |
+
+## Ant Design v6 Deprecated Props
+
+| Deprecated                 | Use Instead             |
+| -------------------------- | ----------------------- |
+| `visible`                  | `open`                  |
+| `direction` (Space)        | `orientation`           |
+| `dropdownMatchSelectWidth` | `popupMatchSelectWidth` |
+
+## Ant Design Static Method Warning
+
+⚠️ **Warning:** `Static function can not consume context like dynamic theme`
+
+```typescript
+// ❌ Wrong - Static import has no context
+import { message } from "antd";
+message.success("Done");  // Warning!
+
+// ✅ Correct - Use App.useApp() hook
+import { App } from "antd";
+
+function MyComponent() {
+  const { message, notification, modal } = App.useApp();
+  message.success("Done");  // ✅ No warning
+}
+```
+
+**Note:**
+- `App` component is already wrapped in `AntdThemeProvider`
+- Just use `App.useApp()` in your component/hook
+- Applies to: `message`, `notification`, `modal`
+
+## Common Mistakes
+
+```typescript
+// ❌ Wrong
+useEffect(() => { fetchData() }, []);  // Use useQuery
+const [users, setUsers] = useState([]);  // Use TanStack for server state
+<Button>Save</Button>  // Use i18n
+
+// ✅ Correct
+const { data } = useQuery({ queryKey, queryFn });
+<Button>{t("common.save")}</Button>
+```
+
+### Form Validation Mistakes
+
+```typescript
+// ❌ Wrong - Hardcoded message in schema
+z.string().min(1, "Name is required")
+
+// ❌ Wrong - Define schema in component
+const schema = z.object({ name: z.string() });
+
+// ❌ Wrong - No field label comment
+<Form.Item name="name" label={label("name")}>
+
+// ✅ Correct - Schema in schemas/, messages in i18n/
+import { userSchemas } from "@/schemas/user";
+{/* Name */}
+<Form.Item name="name" label={label("name")} rules={[zodRule(userSchemas.name, label("name"))]}>
+```
+
+### Form.useForm() Warning
+
+⚠️ **Warning:** `Instance created by useForm is not connected to any Form element`
+
+```typescript
+// ❌ Wrong - Export hook creates unused form instance
+export function useUserForm() {
+  return Form.useForm();  // Instance not connected to any Form!
+}
+
+// ❌ Wrong - Create form instance but don't pass to Form
+const [form] = Form.useForm();
+return <Form>...</Form>  // Missing form={form}
+
+// ✅ Correct - Form instance must connect to Form
+const [form] = Form.useForm();
+return <Form form={form}>...</Form>
+```
+
+**Rule:** Each `Form.useForm()` must have exactly one corresponding `<Form form={form}>`.
+
+### Backend Validation Errors (422)
+
+⚠️ **IMPORTANT:** Form must display errors from backend!
+
+**Form component MUST receive `form` prop from parent:**
+
+```typescript
+// Form component
+interface UserFormProps {
+  form: FormInstance;  // ← REQUIRED
+  onSubmit: (values: UserCreate) => void;
+  // ...
+}
+
+export function UserForm({ form, onSubmit, ... }: UserFormProps) {
+  return (
+    <Form form={form} onFinish={onSubmit}>
+      ...
+    </Form>
+  );
+}
+```
+
+**Page creates form and handles backend errors:**
+
+```typescript
+// Page component
+export default function NewUserPage() {
+  const [form] = Form.useForm();  // ← Create in parent
+
+  const mutation = useMutation({
+    mutationFn: userService.create,
+    onSuccess: () => { ... },
+    onError: (error) => {
+      form.setFields(getFormErrors(error));  // ← Set errors from backend
+    },
+  });
+
+  return (
+    <UserForm
+      form={form}  // ← Pass to form component
+      onSubmit={(values) => mutation.mutate(values)}
+    />
+  );
+}
+```
+
+**Helper `getFormErrors`** (available in `lib/api.ts`):
+
+```typescript
+import { getFormErrors } from "@/lib/api";
+
+// Converts Laravel 422 response to Ant Design format:
+// { errors: { email: ["Email already exists"] } }
+// → [{ name: "email", errors: ["Email already exists"] }]
+```
+
+**Rules:**
+1. Form component does NOT create `Form.useForm()` - receives from parent
+2. Page creates form instance and passes down
+3. `onError` calls `form.setFields(getFormErrors(error))`

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

@@ -0,0 +1,111 @@
+---
+description: "User-editable form requests. MUST read corresponding BaseRequest before editing to avoid duplicating auto-generated validation rules."
+globs: ["{{LARAVEL_BASE}}/Http/Requests/*.php"]
+alwaysApply: true
+---
+
+# Request Editing Rules
+
+These are **user-editable** request files that extend auto-generated BaseRequests.
+
+## ⚠️ BEFORE EDITING - MANDATORY STEPS
+
+### 1. Read the BaseRequest First
+
+Before editing `PostStoreRequest.php`, you **MUST** read `OmnifyBase/PostStoreRequestBase.php` to understand:
+- What validation rules already exist
+- What messages are defined
+- What attributes are set
+
+### 2. Check for Existing Rules
+
+If a rule exists in BaseRequest, **DO NOT** duplicate it here.
+
+## ❌ NEVER DUPLICATE
+
+```php
+// These are ALREADY in BaseRequest - NEVER recreate!
+'title' => ['required', 'string', 'max:255'],  // ❌ From schema
+'email' => ['required', 'email'],               // ❌ From schema
+'status' => ['required', 'in:draft,published'], // ❌ From enum
+```
+
+## ✅ ONLY ADD Custom Validation
+
+```php
+class PostStoreRequest extends PostStoreRequestBase
+{
+    /**
+     * Merge custom rules with base rules
+     */
+    public function rules(): array
+    {
+        return array_merge(parent::rules(), [
+            // ✅ Unique constraint (database-specific)
+            'slug' => ['unique:posts,slug'],
+            
+            // ✅ Complex business rules
+            'published_at' => ['required_if:status,published'],
+            
+            // ✅ Custom format validation
+            'featured_image' => ['url', 'regex:/\.(jpg|png|webp)$/i'],
+        ]);
+    }
+
+    /**
+     * Add custom validation logic
+     */
+    public function withValidator($validator): void
+    {
+        $validator->after(function ($validator) {
+            // ✅ Cross-field validation
+            if ($this->status === 'published' && empty($this->content)) {
+                $validator->errors()->add('content', 'Content is required for published posts.');
+            }
+        });
+    }
+
+    /**
+     * Custom authorization logic
+     */
+    public function authorize(): bool
+    {
+        // ✅ Add authorization check
+        return $this->user()->can('create', Post::class);
+    }
+
+    /**
+     * Prepare data before validation
+     */
+    protected function prepareForValidation(): void
+    {
+        // ✅ Data transformation
+        $this->merge([
+            'slug' => Str::slug($this->title),
+        ]);
+    }
+}
+```
+
+## For Update Requests
+
+```php
+class PostUpdateRequest extends PostUpdateRequestBase
+{
+    public function rules(): array
+    {
+        return array_merge(parent::rules(), [
+            // ✅ Ignore current record for unique check
+            'slug' => ['unique:posts,slug,' . $this->route('post')],
+        ]);
+    }
+}
+```
+
+## Quick Checklist Before Saving
+
+- [ ] Read `OmnifyBase/{Request}Base.php` first
+- [ ] Not duplicating validation rules from BaseRequest
+- [ ] Using `array_merge(parent::rules(), [...])` pattern
+- [ ] Only adding custom/complex validation
+- [ ] Using `parent::authorize()` if BaseRequest has authorization

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

@@ -0,0 +1,125 @@
+---
+description: "User-editable API resources. MUST read corresponding BaseResource before editing to avoid duplicating auto-generated field mappings."
+globs: ["{{LARAVEL_BASE}}/Http/Resources/*.php"]
+alwaysApply: true
+---
+
+# Resource Editing Rules
+
+These are **user-editable** resource files that extend auto-generated BaseResources.
+
+## ⚠️ BEFORE EDITING - MANDATORY STEPS
+
+### 1. Read the BaseResource First
+
+Before editing `PostResource.php`, you **MUST** read `OmnifyBase/PostResourceBase.php` to understand:
+- What fields are already mapped
+- What relations are included
+- How timestamps are formatted
+
+### 2. Check for Existing Fields
+
+If a field exists in BaseResource, **DO NOT** duplicate it here.
+
+## ❌ NEVER DUPLICATE
+
+```php
+// These are ALREADY in BaseResource - NEVER recreate!
+'id' => $this->id,                    // ❌ From schema
+'title' => $this->title,              // ❌ From schema
+'author' => UserResource::make(...),  // ❌ From association
+'created_at' => $this->created_at,    // ❌ Auto-included
+```
+
+## ✅ ONLY ADD Custom Fields
+
+```php
+class PostResource extends PostResourceBase
+{
+    public function toArray($request): array
+    {
+        return array_merge(parent::toArray($request), [
+            // ✅ Computed fields
+            'read_time' => $this->getReadTimeInMinutes(),
+            'word_count' => str_word_count($this->content ?? ''),
+            
+            // ✅ Derived boolean flags
+            'is_published' => $this->status === 'published',
+            'is_featured' => !empty($this->featured_image),
+            
+            // ✅ Formatted data
+            'excerpt_html' => Str::markdown($this->excerpt ?? ''),
+            
+            // ✅ Conditional fields
+            'edit_url' => $this->when(
+                $request->user()?->can('update', $this->resource),
+                route('posts.edit', $this->id)
+            ),
+            
+            // ✅ Aggregated data
+            'comments_count' => $this->whenCounted('comments'),
+            
+            // ✅ Custom relations not in schema
+            'related_posts' => PostResource::collection(
+                $this->whenLoaded('relatedPosts')
+            ),
+        ]);
+    }
+}
+```
+
+## Common Patterns
+
+### Conditional Fields Based on User
+
+```php
+return array_merge(parent::toArray($request), [
+    // Only show to admins
+    'internal_notes' => $this->when(
+        $request->user()?->isAdmin(),
+        $this->internal_notes
+    ),
+]);
+```
+
+### Nested Resource Customization
+
+```php
+return array_merge(parent::toArray($request), [
+    // Override relation resource
+    'author' => $this->whenLoaded('author', function () {
+        return [
+            'id' => $this->author->id,
+            'name' => $this->author->name,
+            // Custom: only include essential fields
+        ];
+    }),
+]);
+```
+
+### Collection Resources
+
+```php
+class PostCollection extends ResourceCollection
+{
+    public function toArray($request): array
+    {
+        return [
+            'data' => $this->collection,
+            // ✅ Add metadata
+            'meta' => [
+                'total_published' => $this->collection->where('status', 'published')->count(),
+            ],
+        ];
+    }
+}
+```
+
+## Quick Checklist Before Saving
+
+- [ ] Read `OmnifyBase/{Resource}Base.php` first
+- [ ] Not duplicating fields from BaseResource
+- [ ] Using `array_merge(parent::toArray($request), [...])` pattern
+- [ ] Only adding computed/custom fields
+- [ ] Using `$this->when()` for conditional fields
+- [ ] Using `$this->whenLoaded()` for optional relations