@malamute/ai-rules 1.0.0

package/configs/nextjs/.claude/rules/testing.md

@@ -0,0 +1,315 @@
+---
+paths:
+  - "**/*.test.tsx"
+  - "**/*.test.ts"
+  - "**/*.spec.tsx"
+  - "**/*.spec.ts"
+  - "**/*.e2e.ts"
+---
+
+# Testing Guidelines (Next.js)
+
+## Framework
+
+- **Vitest** or **Jest** for unit/integration tests
+- **React Testing Library** for component tests
+- **Playwright** for E2E tests
+
+## Test File Structure
+
+```
+component.tsx
+component.test.tsx       # Co-located tests
+
+# or
+__tests__/
+  component.test.tsx
+```
+
+## Component Testing
+
+### Basic Component Test
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { UserCard } from './user-card';
+
+describe('UserCard', () => {
+  const mockUser = { id: '1', name: 'John Doe', email: 'john@example.com' };
+
+  it('should render user information', () => {
+    render(<UserCard user={mockUser} onSelect={vi.fn()} />);
+
+    expect(screen.getByText('John Doe')).toBeInTheDocument();
+    expect(screen.getByText('john@example.com')).toBeInTheDocument();
+  });
+
+  it('should call onSelect when clicked', async () => {
+    const handleSelect = vi.fn();
+    const user = userEvent.setup();
+
+    render(<UserCard user={mockUser} onSelect={handleSelect} />);
+
+    await user.click(screen.getByRole('button'));
+
+    expect(handleSelect).toHaveBeenCalledWith(mockUser);
+  });
+});
+```
+
+### Testing Async Components
+
+```tsx
+import { render, screen } from '@testing-library/react';
+
+// Mock the fetch/data function
+vi.mock('@/lib/api', () => ({
+  getUsers: vi.fn().mockResolvedValue([
+    { id: '1', name: 'John' },
+    { id: '2', name: 'Jane' },
+  ]),
+}));
+
+describe('UsersPage', () => {
+  it('should render users', async () => {
+    // For async Server Components, render and await
+    const Page = await import('./page');
+    render(await Page.default());
+
+    expect(screen.getByText('John')).toBeInTheDocument();
+    expect(screen.getByText('Jane')).toBeInTheDocument();
+  });
+});
+```
+
+### Testing with Providers
+
+```tsx
+import { render } from '@testing-library/react';
+
+function renderWithProviders(ui: React.ReactElement) {
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider>
+        {ui}
+      </ThemeProvider>
+    </QueryClientProvider>
+  );
+}
+
+it('should render with providers', () => {
+  renderWithProviders(<MyComponent />);
+});
+```
+
+## Server Actions Testing
+
+```tsx
+import { createUser } from './actions';
+
+describe('createUser', () => {
+  it('should create a user', async () => {
+    const formData = new FormData();
+    formData.set('name', 'John Doe');
+    formData.set('email', 'john@example.com');
+
+    const result = await createUser(formData);
+
+    expect(result.success).toBe(true);
+  });
+
+  it('should validate input', async () => {
+    const formData = new FormData();
+    formData.set('name', ''); // Invalid
+
+    const result = await createUser(formData);
+
+    expect(result.error).toBeDefined();
+  });
+});
+```
+
+## Hook Testing
+
+```tsx
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './use-counter';
+
+describe('useCounter', () => {
+  it('should increment counter', () => {
+    const { result } = renderHook(() => useCounter());
+
+    expect(result.current.count).toBe(0);
+
+    act(() => {
+      result.current.increment();
+    });
+
+    expect(result.current.count).toBe(1);
+  });
+});
+```
+
+## E2E Testing with Playwright
+
+### Setup
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: 'nx serve app-name',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+### E2E Test Example
+
+```typescript
+// e2e/users.e2e.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Users Page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/users');
+  });
+
+  test('should display user list', async ({ page }) => {
+    await expect(page.getByRole('heading', { name: 'Users' })).toBeVisible();
+    await expect(page.getByTestId('user-list')).toBeVisible();
+  });
+
+  test('should create new user', async ({ page }) => {
+    await page.getByRole('button', { name: 'Add User' }).click();
+
+    await page.getByLabel('Name').fill('John Doe');
+    await page.getByLabel('Email').fill('john@example.com');
+    await page.getByRole('button', { name: 'Submit' }).click();
+
+    await expect(page.getByText('John Doe')).toBeVisible();
+  });
+
+  test('should filter users', async ({ page }) => {
+    await page.getByPlaceholder('Search...').fill('John');
+
+    await expect(page.getByTestId('user-card')).toHaveCount(1);
+  });
+});
+```
+
+### Page Object Pattern
+
+```typescript
+// e2e/pages/users.page.ts
+import { Page, Locator } from '@playwright/test';
+
+export class UsersPage {
+  readonly page: Page;
+  readonly heading: Locator;
+  readonly userList: Locator;
+  readonly searchInput: Locator;
+  readonly addButton: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.heading = page.getByRole('heading', { name: 'Users' });
+    this.userList = page.getByTestId('user-list');
+    this.searchInput = page.getByPlaceholder('Search...');
+    this.addButton = page.getByRole('button', { name: 'Add User' });
+  }
+
+  async goto(): Promise<void> {
+    await this.page.goto('/users');
+  }
+
+  async search(query: string): Promise<void> {
+    await this.searchInput.fill(query);
+  }
+
+  async addUser(name: string, email: string): Promise<void> {
+    await this.addButton.click();
+    await this.page.getByLabel('Name').fill(name);
+    await this.page.getByLabel('Email').fill(email);
+    await this.page.getByRole('button', { name: 'Submit' }).click();
+  }
+}
+```
+
+## Mocking
+
+### Mocking Modules
+
+```tsx
+// Mock entire module
+vi.mock('@/lib/api', () => ({
+  getUsers: vi.fn(),
+  createUser: vi.fn(),
+}));
+
+// Mock with implementation
+import { getUsers } from '@/lib/api';
+
+vi.mocked(getUsers).mockResolvedValue([
+  { id: '1', name: 'John' },
+]);
+```
+
+### Mocking Next.js
+
+```tsx
+// Mock next/navigation
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: vi.fn(),
+    replace: vi.fn(),
+    back: vi.fn(),
+  }),
+  usePathname: () => '/users',
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+// Mock next/headers
+vi.mock('next/headers', () => ({
+  cookies: () => ({
+    get: vi.fn(),
+    set: vi.fn(),
+  }),
+  headers: () => new Headers(),
+}));
+```
+
+## Commands
+
+```bash
+# Run tests
+nx test [project]
+
+# Run with coverage
+nx test [project] --coverage
+
+# Run E2E
+nx e2e [project]-e2e
+
+# Run E2E with UI
+nx e2e [project]-e2e --ui
+
+# Run specific test
+nx test [project] --testFile=user-card.test.tsx
+```
+
+## Coverage Expectations
+
+- >80% coverage on business logic
+- Test all Server Actions
+- Test user interactions
+- E2E for critical user flows

package/configs/nextjs/.claude/settings.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(nx serve *)",
+      "Bash(nx dev *)",
+      "Bash(nx build *)",
+      "Bash(nx test *)",
+      "Bash(nx lint *)",
+      "Bash(nx run-many *)",
+      "Bash(nx affected *)",
+      "Bash(nx g *)",
+      "Bash(nx generate *)",
+      "Bash(npm run *)",
+      "Bash(npm install *)",
+      "Bash(npm ci)",
+      "Bash(npx nx *)",
+      "Read",
+      "Edit",
+      "Write"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(nx reset)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/**)"
+    ]
+  }
+}

package/configs/nextjs/CLAUDE.md

@@ -0,0 +1,376 @@
+# Next.js Project Guidelines
+
+@../_shared/CLAUDE.md
+
+## Stack
+
+- Next.js 15+ (App Router)
+- React 19+
+- TypeScript strict mode
+- Nx monorepo
+
+## Architecture - Nx Structure
+
+```
+apps/
+  [app-name]/
+    app/                        # App Router
+      (routes)/                 # Route groups
+        users/
+          page.tsx
+          _components/          # Private (co-located)
+            user-list.tsx
+        products/
+          page.tsx
+          _components/
+      layout.tsx
+      error.tsx
+      loading.tsx
+
+libs/
+  [domain]/
+    feature/                    # Feature-specific logic
+    ui/                         # Presentational components
+    data-access/                # API calls, server actions
+    util/                       # Helpers
+
+  shared/
+    ui/                         # Design system components
+    util/                       # Shared utilities
+```
+
+### Folder Conventions
+
+| Pattern | Meaning |
+|---------|---------|
+| `_folder/` | Private - not a route, co-located components |
+| `(folder)/` | Route group - organizational, not in URL |
+| `[param]/` | Dynamic segment |
+| `[...param]/` | Catch-all segment |
+| `[[...param]]/` | Optional catch-all |
+
+## React 19 / Next.js 15 - Core Principles
+
+### Server Components by Default
+
+Components are Server Components unless marked with `'use client'`.
+
+```tsx
+// Server Component (default) - runs on server
+// Can: fetch data, access DB, use secrets
+// Cannot: use hooks, browser APIs, event handlers
+export default async function UsersPage() {
+  const users = await fetchUsers();
+  return <UserList users={users} />;
+}
+```
+
+### Client Components
+
+Add `'use client'` directive for interactivity:
+
+```tsx
+'use client';
+
+// Client Component - runs in browser
+// Can: use hooks, event handlers, browser APIs
+// Cannot: directly access DB, use secrets
+import { useState } from 'react';
+
+export function SearchInput({ onSearch }: Props) {
+  const [query, setQuery] = useState('');
+
+  return (
+    <input
+      value={query}
+      onChange={(event) => setQuery(event.target.value)}
+      onKeyDown={(event) => event.key === 'Enter' && onSearch(query)}
+    />
+  );
+}
+```
+
+### When to Use Client Components
+
+| Use Client Component | Use Server Component |
+|---------------------|---------------------|
+| `useState`, `useEffect`, hooks | Data fetching |
+| Event handlers (`onClick`, etc.) | Database access |
+| Browser APIs | Sensitive operations |
+| Interactive UI (forms, modals) | Static content |
+
+## Data Fetching
+
+### Server Components (Preferred)
+
+```tsx
+// app/users/page.tsx
+async function getUsers(): Promise<User[]> {
+  const response = await fetch('https://api.example.com/users', {
+    cache: 'no-store', // Dynamic data
+    // cache: 'force-cache', // Static data (default)
+    // next: { revalidate: 60 }, // ISR - revalidate every 60s
+  });
+  return response.json();
+}
+
+export default async function UsersPage() {
+  const users = await getUsers();
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Server Actions (Mutations)
+
+```tsx
+// app/users/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData): Promise<void> {
+  const name = formData.get('name') as string;
+
+  await db.user.create({ data: { name } });
+
+  revalidatePath('/users');
+}
+```
+
+```tsx
+// app/users/_components/user-form.tsx
+'use client';
+
+import { createUser } from '../actions';
+
+export function UserForm() {
+  return (
+    <form action={createUser}>
+      <input name="name" required />
+      <button type="submit">Create User</button>
+    </form>
+  );
+}
+```
+
+### React 19 Hooks for Data
+
+```tsx
+'use client';
+
+import { useActionState, useOptimistic } from 'react';
+
+// useActionState - form submission state
+const [state, formAction, isPending] = useActionState(createUser, initialState);
+
+// useOptimistic - optimistic UI updates
+const [optimisticItems, addOptimistic] = useOptimistic(
+  items,
+  (state, newItem) => [...state, newItem]
+);
+```
+
+## Component Patterns
+
+### Page Components (Server)
+
+```tsx
+// app/users/page.tsx
+import { UserList } from './_components/user-list';
+import { getUsers } from '@/lib/api';
+
+export default async function UsersPage() {
+  const users = await getUsers();
+
+  return (
+    <main>
+      <h1>Users</h1>
+      <UserList users={users} />
+    </main>
+  );
+}
+```
+
+### Interactive Components (Client)
+
+```tsx
+// app/users/_components/user-list.tsx
+'use client';
+
+import { useState } from 'react';
+import { UserCard } from './user-card';
+
+interface UserListProps {
+  users: User[];
+}
+
+export function UserList({ users }: UserListProps) {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <UserCard
+          key={user.id}
+          user={user}
+          isSelected={user.id === selectedId}
+          onSelect={() => setSelectedId(user.id)}
+        />
+      ))}
+    </ul>
+  );
+}
+```
+
+### Shared UI Components
+
+```tsx
+// libs/shared/ui/button.tsx
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary';
+  isLoading?: boolean;
+}
+
+export function Button({
+  variant = 'primary',
+  isLoading,
+  children,
+  disabled,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={`btn btn-${variant}`}
+      disabled={disabled || isLoading}
+      {...props}
+    >
+      {isLoading ? 'Loading...' : children}
+    </button>
+  );
+}
+```
+
+## Build & Commands
+
+```bash
+# Development
+nx serve [app-name]
+nx dev [app-name]
+
+# Build
+nx build [app-name]
+nx build [app-name] --configuration=production
+
+# Test
+nx test [lib-name]
+nx run-many -t test
+nx affected -t test
+
+# Lint
+nx lint [project-name]
+nx run-many -t lint
+
+# Generate
+nx g @nx/next:component [name] --project=[app]
+nx g @nx/react:component [name] --project=[lib]
+nx g @nx/next:page [name] --project=[app]
+```
+
+## Code Style
+
+### Component Files
+
+- One component per file
+- Named exports (not default) for reusable components
+- Default export only for pages (`page.tsx`)
+- Props interface above component
+
+```tsx
+// Good
+interface UserCardProps {
+  user: User;
+  onSelect: () => void;
+}
+
+export function UserCard({ user, onSelect }: UserCardProps) {
+  return (/* ... */);
+}
+```
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Components | PascalCase | `UserCard` |
+| Files | kebab-case | `user-card.tsx` |
+| Hooks | camelCase with `use` | `useUserData` |
+| Server Actions | camelCase | `createUser` |
+| Route folders | kebab-case | `user-profile/` |
+
+### Imports Order
+
+```tsx
+// 1. React/Next
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+
+// 2. External libraries
+import { z } from 'zod';
+
+// 3. Internal libs (@/)
+import { Button } from '@/components/ui/button';
+import { getUsers } from '@/lib/api';
+
+// 4. Relative imports
+import { UserCard } from './user-card';
+
+// 5. Types
+import type { User } from '@/types';
+```
+
+## Error Handling
+
+### Error Boundaries
+
+```tsx
+// app/users/error.tsx
+'use client';
+
+interface ErrorProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+export default function Error({ error, reset }: ErrorProps) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+### Loading States
+
+```tsx
+// app/users/loading.tsx
+export default function Loading() {
+  return <div>Loading...</div>;
+}
+```
+
+## Performance
+
+- Use Server Components for data-heavy UI
+- Lazy load heavy Client Components with `next/dynamic`
+- Use `<Image>` from `next/image` for optimized images
+- Use `<Link>` from `next/link` for client-side navigation
+- Avoid `useEffect` for data fetching - use Server Components or `use()`