create-tigra 1.0.0

package/template/.claude/rules/client-10-testing-strategy.md

@@ -0,0 +1,371 @@
+---
+trigger: always_on
+globs: "client/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **client** directory.
+
+# Client Testing Strategy
+
+## Stack
+
+```json
+{
+  "devDependencies": {
+    "vitest": "^1.0.0",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@testing-library/jest-dom": "^6.1.0",
+    "msw": "^2.0.0"
+  }
+}
+```
+
+## Setup
+
+```typescript
+// src/test/setup.ts
+import { expect, afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+import matchers from '@testing-library/jest-dom/matchers';
+
+expect.extend(matchers);
+afterEach(() => cleanup());
+
+// Mock window.matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  })),
+});
+```
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './src/test/setup.ts',
+  },
+});
+```
+
+## Test Utilities
+
+```typescript
+// src/test/utils.tsx
+import { render } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { Provider } from 'react-redux';
+import { store } from '@/store';
+
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+export function renderWithProviders(ui: React.ReactElement, options = {}) {
+  const queryClient = createTestQueryClient();
+
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <Provider store={store}>
+        <QueryClientProvider client={queryClient}>
+          <BrowserRouter>{children}</BrowserRouter>
+        </QueryClientProvider>
+      </Provider>
+    );
+  }
+
+  return { ...render(ui, { wrapper: Wrapper, ...options }), queryClient };
+}
+
+export * from '@testing-library/react';
+export { renderWithProviders as render };
+```
+
+## API Mocking (MSW)
+
+```typescript
+// src/test/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  http.post('/api/v1/auth/login', async ({ request }) => {
+    const { email, password } = await request.json();
+    
+    if (email === 'user@test.com' && password === 'password') {
+      return HttpResponse.json({
+        success: true,
+        data: {
+          user: { id: '1', email: 'user@test.com' },
+          tokens: { accessToken: 'fake-token' },
+        },
+      });
+    }
+    
+    return HttpResponse.json(
+      { success: false, error: { code: 'INVALID_CREDENTIALS' } },
+      { status: 401 }
+    );
+  }),
+
+  http.get('/api/v1/resources', () => {
+    return HttpResponse.json({
+      success: true,
+      data: {
+        items: [
+          { id: '1', title: 'Resource 1', price: 100 },
+          { id: '2', title: 'Resource 2', price: 200 },
+        ],
+        pagination: { page: 1, totalPages: 1, hasNextPage: false },
+      },
+    });
+  }),
+];
+```
+
+```typescript
+// src/test/mocks/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+```
+
+```typescript
+// src/test/setup.ts (add to existing)
+import { server } from './mocks/server';
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+## Testing Patterns
+
+### 1. Component Tests
+
+```typescript
+// ResourceCard.test.tsx
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@/test/utils';
+import { ResourceCard } from './ResourceCard';
+
+describe('ResourceCard', () => {
+  const mockResource = {
+    id: '1',
+    title: 'Test Resource',
+    price: 99.99,
+  };
+
+  it('renders resource information', () => {
+    render(<ResourceCard resource={mockResource} />);
+    
+    expect(screen.getByText('Test Resource')).toBeInTheDocument();
+    expect(screen.getByText('$99.99')).toBeInTheDocument();
+  });
+
+  it('calls onClick when clicked', async () => {
+    const handleClick = vi.fn();
+    const { user } = render(
+      <ResourceCard resource={mockResource} onClick={handleClick} />
+    );
+    
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalledWith('1');
+  });
+});
+```
+
+### 2. Page/Container Tests
+
+```typescript
+// ResourcesPage.test.tsx
+import { render, screen, waitFor } from '@/test/utils';
+
+describe('ResourcesPage', () => {
+  it('displays loading state initially', () => {
+    render(<ResourcesPage />);
+    expect(screen.getByRole('status')).toBeInTheDocument();
+  });
+
+  it('renders resources after loading', async () => {
+    render(<ResourcesPage />);
+    
+    await waitFor(() => {
+      expect(screen.getByText('Resource 1')).toBeInTheDocument();
+    });
+  });
+
+  it('handles API errors', async () => {
+    server.use(
+      http.get('/api/v1/resources', () => {
+        return HttpResponse.json(
+          { success: false, error: { message: 'Error' } },
+          { status: 500 }
+        );
+      })
+    );
+    
+    render(<ResourcesPage />);
+    
+    await waitFor(() => {
+      expect(screen.getByText(/error/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+### 3. Form Tests
+
+```typescript
+// ResourceForm.test.tsx
+import userEvent from '@testing-library/user-event';
+
+describe('ResourceForm', () => {
+  it('submits valid form data', async () => {
+    const handleSubmit = vi.fn();
+    const user = userEvent.setup();
+    
+    render(<ResourceForm onSubmit={handleSubmit} />);
+    
+    await user.type(screen.getByLabelText(/title/i), 'New Resource');
+    await user.type(screen.getByLabelText(/price/i), '99.99');
+    await user.click(screen.getByRole('button', { name: /submit/i }));
+    
+    await waitFor(() => {
+      expect(handleSubmit).toHaveBeenCalledWith({
+        title: 'New Resource',
+        price: 99.99,
+      });
+    });
+  });
+
+  it('displays validation errors', async () => {
+    const user = userEvent.setup();
+    render(<ResourceForm onSubmit={vi.fn()} />);
+    
+    await user.click(screen.getByRole('button', { name: /submit/i }));
+    
+    await waitFor(() => {
+      expect(screen.getByText(/title is required/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+### 4. Hook Tests
+
+```typescript
+// useResources.test.tsx
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  
+  return ({ children }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+};
+
+describe('useResources', () => {
+  it('fetches resources successfully', async () => {
+    const { result } = renderHook(() => useResources(), {
+      wrapper: createWrapper(),
+    });
+    
+    expect(result.current.isLoading).toBe(true);
+    
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+    
+    expect(result.current.data).toHaveLength(2);
+  });
+});
+```
+
+### 5. User Flow Tests
+
+```typescript
+// login-flow.test.tsx
+describe('Login Flow', () => {
+  it('allows user to login', async () => {
+    const user = userEvent.setup();
+    render(<App />, { initialRoute: '/login' });
+    
+    await user.type(screen.getByLabelText(/email/i), 'user@test.com');
+    await user.type(screen.getByLabelText(/password/i), 'password');
+    await user.click(screen.getByRole('button', { name: /login/i }));
+    
+    await waitFor(() => {
+      expect(screen.getByText(/dashboard/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+## Best Practices
+
+### ✅ DO:
+```typescript
+// Test what user sees
+expect(screen.getByText('Resource 1')).toBeInTheDocument();
+
+// Use user-event for interactions
+await user.click(screen.getByRole('button'));
+
+// Wait for async updates
+await waitFor(() => {
+  expect(screen.getByText('Success')).toBeInTheDocument();
+});
+```
+
+### ❌ DON'T:
+```typescript
+// Don't test implementation details
+expect(component.state.isLoading).toBe(false); // BAD
+
+// Don't use test IDs unnecessarily
+screen.getByTestId('card'); // Prefer semantic queries
+
+// Don't test third-party libraries
+expect(mockRouter.navigate).toHaveBeenCalled(); // BAD
+```
+
+## Coverage Requirements
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+**Minimum:**
+- Hooks: 80%
+- Components: 70%
+- Utils: 90%
+- Overall: 70%
+
+## Checklist
+
+- [ ] Test setup configured (RTL + MSW)
+- [ ] All critical user flows tested
+- [ ] Forms validated and tested
+- [ ] API mocking for endpoints
+- [ ] 70%+ code coverage
+- [ ] Tests run in CI

package/template/.claude/rules/global-ai-edit-safety.md

@@ -0,0 +1,39 @@
+---
+trigger: always_on
+globs: "**/*"
+---
+
+> **SCOPE**: These rules apply to the entire workspace (**server** and **client**).
+
+# API Server – Safe Editing Rules
+
+## General safety
+
+- Assume this is a real production project. Avoid destructive or experimental changes.
+- Never delete or radically restructure large parts of the codebase unless explicitly requested.
+
+## When modifying existing code
+
+- Keep changes as **small and focused** as possible.
+- Do not change:
+  - Existing function signatures unless explicitly asked.
+  - Existing exports/imports that other modules depend on.
+- If you must introduce a breaking change, call it out clearly in the explanation.
+
+## Backwards compatibility
+
+- When adding new features, prefer extending modules over rewiring everything.
+- Preserve existing behavior for:
+  - Auth
+  - Core business flows
+  - Payment flows
+
+## Comments & TODOs
+
+- If something is ambiguous, add a `// TODO:` comment with a short note.
+- Do NOT leave half-implemented features without a TODO or explanation.
+
+## Logs & debugging
+
+- Do not add noisy debug logs.
+- If temporary logs are necessary, clearly mark them with `// TODO: remove debug log` so they can be cleaned up.

package/template/.claude/rules/server-01-db-and-migrations.md

@@ -0,0 +1,243 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# API Server – Database & Migrations Rules
+
+## 🎯 Core Principles
+
+- **Primary Database**: MySQL 8.0+
+- **ORM**: Prisma (version 6.x - DO NOT upgrade to 7.x without testing)
+- **Migration Philosophy**: 
+  - Development: Fast iteration with resets
+  - Production: Safe, forward-only migrations
+- **Schema Source of Truth**: `prisma/schema.prisma`
+
+---
+
+## 🚫 CRITICAL RULES - NEVER BREAK THESE
+
+### Rule 1: NO Manual Schema Changes
+❌ **NEVER** run raw SQL to change schema (CREATE TABLE, ALTER TABLE, etc.)  
+✅ **ALWAYS** use Prisma migrations for schema changes  
+✅ **EXCEPTION**: Data changes (INSERT, UPDATE, DELETE) can be raw SQL
+
+### Rule 2: Development vs Production Workflows
+**Development** (when iterating on schema):
+```bash
+npm run prisma:reset        # Drops everything, reruns migrations
+npm run prisma:seed         # Repopulate test data
+```
+
+**Production** (deployed servers):
+```bash
+npm run prisma:migrate deploy   # Only applies new migrations, NEVER resets
+```
+
+### Rule 3: Migration Conflicts = Reset
+When you get migration errors in **development**:
+- ❌ DON'T try to fix migration files manually
+- ❌ DON'T delete migration folders
+- ✅ DO run `npm run prisma:reset` to start clean
+
+### Rule 4: Never Use `prisma db push` in Production
+- `prisma db push` = Quick prototyping, no migration history
+- `prisma migrate dev` = Proper migrations with history
+- Use `db push` ONLY when rapidly prototyping new features
+
+---
+
+## 📁 Naming Conventions
+
+### Tables
+- Format: `snake_case` plural
+- Examples: `users`, `posts`, `categories`
+
+### Columns
+- Format: `snake_case`
+- Timestamps: `created_at`, `updated_at`, `deleted_at`
+- Foreign keys: `<table_singular>_id`
+  - Example: `user_id`, `category_id`
+
+### Prisma Models
+- Format: `PascalCase` singular
+- Example: `User`, `Post`, `Category`
+
+---
+
+## 🗄️ Required Fields for Every Table
+
+Every main entity table MUST have:
+```prisma
+model EntityName {
+  id        String   @id @default(uuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+```
+
+Optional but recommended:
+```prisma
+  deletedAt DateTime?  // For soft deletes
+  isActive  Boolean @default(true)  // For disabling without deleting
+```
+
+---
+
+## 🔗 Architecture Relationships
+
+### Core Entities (Example)
+```
+users (1) ──→ (many) posts
+users (1) ──→ (1) profiles
+categories (1) ──→ (many) posts
+```
+
+### Media Attachments
+For images/files attached to multiple entity types:
+```prisma
+model Media {
+  id         String @id @default(uuid())
+  entityType String // 'post', 'user', 'product'
+  entityId   String // ID of the related entity
+  url        String
+  type       String // 'image', 'video', 'document'
+  order      Int    // For sorting galleries
+  
+  @@index([entityType, entityId])
+}
+```
+
+---
+
+## ⚡ Indexing Strategy
+
+### Always Index These:
+1. **Foreign Keys** - Prisma auto-indexes, but verify:
+```prisma
+   @@index([userId])
+```
+
+2. **Filter Columns** - Fields used in WHERE clauses:
+```prisma
+   @@index([isActive])
+   @@index([status])
+```
+
+3. **Composite Indexes** - Multiple columns filtered together:
+```prisma
+   @@index([categoryId, isActive])
+```
+
+4. **Unique Constraints** - Business logic requirements:
+```prisma
+   @@unique([email])
+   @@unique([slug])
+```
+
+### When NOT to Index:
+- Low-cardinality boolean fields used alone (e.g., `isActive` by itself)
+- Text/blob columns
+- Fields never used in WHERE/ORDER BY
+
+---
+
+## 🔄 Migration Workflow
+
+### When Making Schema Changes:
+
+#### Step 1: Edit `prisma/schema.prisma`
+```prisma
+model Resource {
+  id          String   @id @default(uuid())
+  title       String
+  description String?  @db.Text  // NEW FIELD
+  // ... rest of fields
+}
+```
+
+#### Step 2: Create Migration (Development)
+```bash
+# Option A: With descriptive name
+npm run prisma:migrate dev --name add_resource_description
+
+# Option B: If migration conflicts occur
+npm run prisma:reset  # Nuclear option - drops everything
+npm run prisma:seed   # Repopulate test data
+```
+
+---
+
+## 🚀 Production Deployment Workflow
+
+### Pre-Deployment Checklist:
+1. ✅ All migrations tested locally
+2. ✅ Seed data runs successfully
+3. ✅ No pending schema changes in `schema.prisma`
+4. ✅ Migration files committed to git
+
+### Deployment Commands:
+```bash
+# On production server:
+npm run prisma:migrate deploy  # Applies pending migrations only
+npm run prisma:generate        # Regenerates client with new schema
+npm start                      # Restart application
+```
+
+---
+
+## 📊 Data Integrity Rules
+
+### Foreign Keys
+- ✅ **USE** foreign keys for core relationships
+- ✅ **USE** `onDelete: Cascade` for dependent data
+```prisma
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+```
+
+### Soft Deletes
+Prefer soft deletes for user-generated content:
+```prisma
+model Resource {
+  deletedAt DateTime?
+  // Query helper: where: { deletedAt: null }
+}
+```
+
+---
+
+## 🛠️ Troubleshooting Guide
+
+### Issue: "Environment variable not found: DATABASE_URL"
+**Solution:**
+```bash
+# Verify .env exists and has:
+DATABASE_URL="mysql://user:pass@localhost:3306/dbname"
+```
+
+### Issue: "Prisma Client is not generated"
+**Solution:**
+```bash
+npm run prisma:generate
+```
+
+---
+
+## 🎯 Best Practices Summary
+
+### ✅ DO:
+- Use Prisma migrations for ALL schema changes
+- Reset database freely in development
+- Test migrations in staging before production
+- Add indexes for frequently queried fields
+- Use soft deletes for user content
+- Commit migration files to git
+
+### ❌ DON'T:
+- Manually edit database schema
+- Use `prisma:reset` in production
+- Skip migrations and use `db push` in production
+- Delete migration files