@relipa/ai-flow-kit 0.2.0 → 0.2.1

package/custom/rules/javascript/reactjs-examples.md

@@ -0,0 +1,380 @@
+# React.js Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## Component Rules
+
+### Always use Functional Components
+
+```tsx
+// ✅ Good
+const UserCard = ({ user }: UserCardProps) => {
+  return <div>{user.name}</div>;
+};
+
+// ❌ Bad — class component
+class UserCard extends React.Component {}
+```
+
+### Define Props with TypeScript interface
+
+```tsx
+// ✅ Good
+interface UserCardProps {
+  user: User;
+  onDelete?: (id: number) => void;
+  className?: string;
+}
+
+const UserCard = ({ user, onDelete, className }: UserCardProps) => {
+  // ...
+};
+
+// ❌ Bad — any, or no type
+const UserCard = ({ user }: any) => {};
+const UserCard = (props) => {};
+```
+
+### Keep components focused and small
+
+```tsx
+// ✅ Good — logic extracted to hook
+const UserList = () => {
+  const { users, isLoading, error, deleteUser } = useUserList();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage message={error.message} />;
+
+  return (
+    <ul>
+      {users.map(user => (
+        <UserCard key={user.id} user={user} onDelete={deleteUser} />
+      ))}
+    </ul>
+  );
+};
+
+// ❌ Bad — logic mixed into component
+const UserList = () => {
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(data => { setUsers(data); setLoading(false); });
+  }, []);
+
+  const handleDelete = async (id) => {
+    await fetch(`/api/users/${id}`, { method: 'DELETE' });
+    setUsers(prev => prev.filter(u => u.id !== id));
+  };
+  // ... long JSX
+};
+```
+
+### Export convention
+
+```tsx
+// Named export for regular components
+export const UserCard = ({ user }: UserCardProps) => { ... };
+
+// Default export only for page-level components
+export default function UserPage() { ... }
+```
+
+---
+
+## Custom Hook Rules
+
+```tsx
+// ✅ Good
+const useUserList = () => {
+  const { data: users = [], isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: userApi.getAll,
+  });
+
+  const { mutate: deleteUser } = useMutation({
+    mutationFn: userApi.delete,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  });
+
+  return { users, isLoading, error, deleteUser };
+};
+
+// Usage
+const { users, isLoading, deleteUser } = useUserList();
+```
+
+---
+
+## State Management Rules
+
+### Server state → TanStack Query
+
+```tsx
+// Fetching
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users', filters],   // include deps in key
+  queryFn: () => userApi.getAll(filters),
+  staleTime: 5 * 60 * 1000,      // 5 minutes
+});
+
+// Mutation
+const { mutate, isPending } = useMutation({
+  mutationFn: userApi.create,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['users'] });
+    toast.success('User created');
+  },
+  onError: (error) => toast.error(error.message),
+});
+```
+
+### Client/UI state → Zustand (or useState for local)
+
+```tsx
+// Local state — use useState
+const [isOpen, setIsOpen] = useState(false);
+
+// Shared UI state — use Zustand
+const useAuthStore = create<AuthStore>((set) => ({
+  user: null,
+  token: null,
+  login: (user, token) => set({ user, token }),
+  logout: () => set({ user: null, token: null }),
+}));
+```
+
+---
+
+## Form Rules
+
+Use **React Hook Form + Zod** for all forms:
+
+```tsx
+// 1. Define schema with Zod
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email'),
+  fullName: z.string().min(2, 'Min 2 characters').max(100),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+type CreateUserForm = z.infer<typeof createUserSchema>;
+
+// 2. Use in component
+const CreateUserForm = () => {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<CreateUserForm>({
+    resolver: zodResolver(createUserSchema),
+  });
+
+  const onSubmit = async (data: CreateUserForm) => {
+    await createUser(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Saving...' : 'Create'}
+      </button>
+    </form>
+  );
+};
+```
+
+---
+
+## API Layer Rules
+
+One `axios` instance shared across the app with interceptors:
+
+```tsx
+// src/services/api.ts
+const api = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  timeout: 10000,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// Attach token automatically
+api.interceptors.request.use((config) => {
+  const token = useAuthStore.getState().token;
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+// Handle 401 globally
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      useAuthStore.getState().logout();
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+Feature API module:
+
+```tsx
+// src/features/users/api.ts
+export const userApi = {
+  getAll: (params?: UserListParams): Promise<User[]> =>
+    api.get('/users', { params }).then(r => r.data),
+
+  getById: (id: number): Promise<User> =>
+    api.get(`/users/${id}`).then(r => r.data),
+
+  create: (data: CreateUserRequest): Promise<User> =>
+    api.post('/users', data).then(r => r.data),
+
+  update: (id: number, data: UpdateUserRequest): Promise<User> =>
+    api.put(`/users/${id}`, data).then(r => r.data),
+
+  delete: (id: number): Promise<void> =>
+    api.delete(`/users/${id}`).then(r => r.data),
+};
+```
+
+---
+
+## TypeScript Rules
+
+```tsx
+// ✅ Good
+interface User {
+  id: number;
+  email: string;
+  fullName: string;
+  createdAt: string;
+}
+
+type UserStatus = 'active' | 'inactive' | 'banned';
+
+const getUser = async (id: number): Promise<User> => {
+  return api.get(`/users/${id}`).then(r => r.data);
+};
+
+// ❌ Bad
+const getUser = async (id: any) => {
+  return api.get(`/users/${id}`).then((r: any) => r.data);
+};
+```
+
+---
+
+## Styling Rules (Tailwind CSS)
+
+```tsx
+// ✅ Good — cn() for conditional classes
+import { cn } from '\@/utils/cn';
+
+const Button = ({ variant = 'primary', disabled, className, children }: ButtonProps) => (
+  <button
+    className={cn(
+      'px-4 py-2 rounded font-medium transition-colors',
+      variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
+      variant === 'outline' && 'border border-gray-300 hover:bg-gray-50',
+      disabled && 'opacity-50 cursor-not-allowed',
+      className
+    )}
+    disabled={disabled}
+  >
+    {children}
+  </button>
+);
+
+// ❌ Bad — inline style
+<button style={{ backgroundColor: 'blue', padding: '8px 16px' }}>
+```
+
+---
+
+## Performance Rules
+
+```tsx
+// Lazy routes
+const UserPage = React.lazy(() => import('./pages/UserPage'));
+
+<Suspense fallback={<PageSkeleton />}>
+  <UserPage />
+</Suspense>
+
+// useMemo for expensive computation
+const sortedUsers = useMemo(
+  () => [...users].sort((a, b) => a.fullName.localeCompare(b.fullName)),
+  [users]
+);
+```
+
+---
+
+## Error Handling Rules
+
+```tsx
+// Error boundary at route level
+<ErrorBoundary fallback={<ErrorPage />}>
+  <Routes>
+    <Route path="/users" element={<UserPage />} />
+  </Routes>
+</ErrorBoundary>
+
+// Async error handling
+const { mutate } = useMutation({
+  mutationFn: userApi.create,
+  onSuccess: () => toast.success('User created successfully'),
+  onError: (error: AxiosError<ApiError>) =>
+    toast.error(error.response?.data?.message ?? 'Something went wrong'),
+});
+```
+
+---
+
+## Testing Rules
+
+### Unit/Component tests with React Testing Library
+
+```tsx
+// Test behavior, not implementation
+describe('UserCard', () => {
+  it('should display user name and email', () => {
+    const user: User = { id: 1, email: 'test\@example.com', fullName: 'Test User' };
+    render(<UserCard user={user} />);
+
+    expect(screen.getByText('Test User')).toBeInTheDocument();
+    expect(screen.getByText('test\@example.com')).toBeInTheDocument();
+  });
+
+  it('should call onDelete with user id when delete button clicked', async () => {
+    const onDelete = vi.fn();
+    const user: User = { id: 1, email: 'test\@example.com', fullName: 'Test User' };
+
+    render(<UserCard user={user} onDelete={onDelete} />);
+    await userEvent.click(screen.getByRole('button', { name: /delete/i }));
+
+    expect(onDelete).toHaveBeenCalledWith(1);
+  });
+});
+```
+
+### Hook tests
+
+```tsx
+import { renderHook, waitFor } from '\@testing-library/react';
+
+it('should fetch users', async () => {
+  const { result } = renderHook(() => useUserList(), { wrapper: QueryWrapper });
+
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+  expect(result.current.users).toHaveLength(2);
+});
+```

package/custom/rules/javascript/reactjs-rules.md

@@ -0,0 +1,173 @@
+# React.js Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any React code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── ui/                   # Generic, reusable UI (Button, Input, Modal...)
+│   └── [feature]/            # Feature-specific components
+├── pages/                    # Route-level components (thin, delegate to features)
+├── features/                 # Self-contained feature modules
+│   └── [feature]/
+│       ├── components/       # UI specific to this feature
+│       ├── hooks/            # Custom hooks for this feature
+│       ├── api.ts            # API calls for this feature
+│       ├── store.ts          # Zustand slice (if needed)
+│       ├── types.ts          # TypeScript types/interfaces
+│       └── index.ts          # Public exports
+├── hooks/                    # Shared custom hooks
+├── services/
+│   └── api.ts                # Axios instance + interceptors
+├── store/                    # Global Zustand store
+├── types/                    # Shared TypeScript types
+├── utils/                    # Pure utility functions
+├── constants/                # App-wide constants
+└── App.tsx
+```
+
+---
+
+## Component Rules
+
+### Always use Functional Components
+
+- Never use class components.
+
+### Define Props with TypeScript interface
+
+- No `any`, no untyped `props` param.
+
+### Keep components focused and small
+
+- One component = one responsibility
+- If a component exceeds ~150 lines, split it
+- Extract logic to custom hooks, keep JSX clean
+
+### Export convention
+
+- Named export for regular components.
+- Default export only for page-level components.
+
+---
+
+## Custom Hook Rules
+
+- Prefix with `use`: `useUserList`, `useAuth`, `useModal`
+- Extract all side effects, API calls, and complex state from components
+- Return objects (not arrays) for multiple values — easier to destructure
+
+---
+
+## State Management Rules
+
+### Server state → TanStack Query
+
+Use for all API data (fetching, caching, mutations).
+
+### Client/UI state → Zustand (or useState for local)
+
+### Rules:
+- **Never** use global state for server/API data — that's TanStack Query's job
+- **Never** fetch in `useEffect` manually — use TanStack Query
+- **Never** put loading/error state in Zustand — TanStack Query handles that
+
+---
+
+## Form Rules
+
+Use **React Hook Form + Zod** for all forms — define the schema with Zod, infer the form type from it, wire it into `useForm` via `zodResolver`.
+
+---
+
+## API Layer Rules
+
+One `axios` instance shared across the app with interceptors (attach auth token on request, handle 401 globally on response). Each feature gets its own thin API module built on that instance.
+
+---
+
+## TypeScript Rules
+
+- **No `any`** — use `unknown`, proper types, or generics
+- Define shared types in `types.ts` files
+- Use `interface` for object shapes, `type` for unions/intersections
+- Always type function return values for public hooks and API functions
+
+---
+
+## Styling Rules (Tailwind CSS)
+
+- Use utility classes directly — avoid custom CSS unless necessary
+- Extract repeated class combinations into components or a `cn()` helper
+- Use `className` prop for external style overrides
+- Never use inline `style={{ }}` for anything Tailwind can express
+
+---
+
+## Performance Rules
+
+- Use `React.memo` only when profiling shows a real problem — do not optimize prematurely
+- Use `useMemo` / `useCallback` for expensive computations or stable references passed to children
+- Lazy-load routes with `React.lazy` + `Suspense`
+- Avoid anonymous functions in JSX props when passing to memoized children
+
+---
+
+## Error Handling Rules
+
+- Use React Error Boundary at the route level
+- Handle API errors in TanStack Query `onError` callbacks
+- Show user-friendly messages — never raw error objects
+- Use toast notifications for async operation feedback
+
+---
+
+## Testing Rules
+
+### Unit/Component tests with React Testing Library
+
+- Test behavior, not implementation.
+
+### Hook tests
+
+- Use `renderHook` + `waitFor` from `@testing-library/react`.
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Component file | PascalCase | `UserCard.tsx` |
+| Hook file | camelCase | `useUserList.ts` |
+| Utility file | camelCase | `formatDate.ts` |
+| Type/Interface | PascalCase | `User`, `CreateUserRequest` |
+| Component | PascalCase | `UserCard`, `OrderList` |
+| Hook | `use` + PascalCase | `useUserList`, `useAuth` |
+| Event handler | `handle` + Action | `handleDelete`, `handleSubmit` |
+| Boolean variable | `is/has/can` prefix | `isLoading`, `hasError`, `canEdit` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY`, `API_TIMEOUT` |
+| CSS class (custom) | kebab-case | `user-card`, `nav-item` |
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ Fetching in `useEffect` → use TanStack Query
+- ❌ Using `any` type → define proper TypeScript types
+- ❌ Storing server data in Zustand → that's TanStack Query's responsibility
+- ❌ Class components → use functional components
+- ❌ `index.js` everywhere → use named files for traceability
+- ❌ Direct DOM manipulation → use React state/refs
+- ❌ Mutating state directly → always use setter functions
+- ❌ Large components doing everything → split into smaller focused components
+- ❌ Prop drilling more than 2 levels → use context or Zustand
+- ❌ Hardcoding API URLs → use `import.meta.env.VITE_API_URL`
+
+---
+
+When explaining changes, refer to the [React Official Documentation](https://react.dev), [TanStack Query](https://tanstack.com/query), and [React Hook Form](https://react-hook-form.com) conventions.

package/custom/rules/php/php-examples.md

@@ -0,0 +1,161 @@
+# PHP Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## General
+
+```php
+// ✅ Good
+declare(strict_types=1);
+
+class UserService
+{
+    public function __construct(
+        private readonly UserRepository $userRepository,
+    ) {}
+
+    public function findById(int $id): UserDto
+    {
+        $user = $this->userRepository->findById($id);
+        if ($user === null) {
+            throw new NotFoundException("User $id not found");
+        }
+        return UserDto::fromArray($user);
+    }
+}
+
+// ❌ Bad — no strict types, logic in global scope
+$pdo = new PDO(...);
+$user = $pdo->query("SELECT * FROM users WHERE id = $_GET[id]")->fetch();
+echo $user['name'];
+```
+
+---
+
+## Security
+
+```php
+// ✅ Good — prepared statement
+$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email');
+$stmt->execute([':email' => $email]);
+$user = $stmt->fetch(PDO::FETCH_ASSOC);
+
+// ✅ Good — safe HTML output
+echo htmlspecialchars($user['name'], ENT_QUOTES, 'UTF-8');
+
+// ❌ Bad — SQL injection
+$result = $pdo->query("SELECT * FROM users WHERE email = '$email'");
+```
+
+---
+
+## Database / Repository
+
+```php
+// ✅ Good
+class UserRepository
+{
+    public function __construct(private readonly \PDO $pdo) {}
+
+    public function findByEmail(string $email): ?array
+    {
+        $stmt = $this->pdo->prepare(
+            'SELECT id, email, full_name FROM users WHERE email = :email AND deleted = 0'
+        );
+        $stmt->execute([':email' => $email]);
+        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
+        return $row ?: null;
+    }
+
+    public function create(string $email, string $fullName, string $passwordHash): int
+    {
+        $stmt = $this->pdo->prepare(
+            'INSERT INTO users (email, full_name, password_hash) VALUES (:email, :full_name, :password_hash)'
+        );
+        $stmt->execute([
+            ':email'         => $email,
+            ':full_name'     => $fullName,
+            ':password_hash' => $passwordHash,
+        ]);
+        return (int) $this->pdo->lastInsertId();
+    }
+}
+```
+
+---
+
+## Controller
+
+```php
+// ✅ Good
+declare(strict_types=1);
+
+class UserController
+{
+    public function __construct(private readonly UserService $userService) {}
+
+    public function create(): void
+    {
+        $body = json_decode(file_get_contents('php://input'), true) ?? [];
+        $email    = trim($body['email'] ?? '');
+        $fullName = trim($body['full_name'] ?? '');
+        $password = $body['password'] ?? '';
+
+        if ($email === '' || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
+            http_response_code(400);
+            echo json_encode(['error' => 'Invalid email']);
+            return;
+        }
+
+        $user = $this->userService->create($email, $fullName, $password);
+        http_response_code(201);
+        echo json_encode($user);
+    }
+}
+```
+
+---
+
+## Error Handling
+
+```php
+// ✅ Good — centralised handler
+set_exception_handler(function (\Throwable $e): void {
+    $status = match (true) {
+        $e instanceof NotFoundException      => 404,
+        $e instanceof ValidationException    => 422,
+        $e instanceof UnauthorizedException  => 401,
+        default                              => 500,
+    };
+    http_response_code($status);
+    header('Content-Type: application/json');
+    if ($status === 500) {
+        error_log($e->getMessage() . ' ' . $e->getTraceAsString());
+        echo json_encode(['error' => 'Internal server error']);
+    } else {
+        echo json_encode(['error' => $e->getMessage()]);
+    }
+});
+```
+
+---
+
+## Testing
+
+```php
+class UserServiceTest extends TestCase
+{
+    public function testCreateThrowsOnDuplicateEmail(): void
+    {
+        $repo = $this->createMock(UserRepository::class);
+        $repo->method('findByEmail')->willReturn(['id' => 1]);
+
+        $service = new UserService($repo);
+
+        $this->expectException(ValidationException::class);
+        $service->create('dup@example.com', 'Test', 'password');
+    }
+}
+```