ultra-dex 1.7.2 → 1.8.0

package/assets/cursor-rules/06-testing.mdc

@@ -0,0 +1,104 @@
+# Testing Rules
+
+## Test Stack
+
+- Unit/Integration: Vitest
+- E2E: Playwright
+- API: Supertest or native fetch
+
+## File Structure
+
+```
+tests/
+├── unit/           # Pure function tests
+├── integration/    # API + DB tests
+└── e2e/            # Full user flow tests
+```
+
+## Unit Tests
+
+```typescript
+// tests/unit/utils.test.ts
+import { describe, it, expect } from 'vitest';
+import { formatCurrency } from '@/lib/utils';
+
+describe('formatCurrency', () => {
+  it('formats USD correctly', () => {
+    expect(formatCurrency(1999, 'USD')).toBe('$19.99');
+  });
+
+  it('handles zero', () => {
+    expect(formatCurrency(0, 'USD')).toBe('$0.00');
+  });
+});
+```
+
+## API Integration Tests
+
+```typescript
+// tests/integration/api/users.test.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { prisma } from '@/lib/prisma';
+
+describe('POST /api/users', () => {
+  beforeEach(async () => {
+    await prisma.user.deleteMany();
+  });
+
+  it('creates a user with valid data', async () => {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ email: 'test@example.com', name: 'Test' }),
+    });
+    expect(res.status).toBe(201);
+
+    const user = await prisma.user.findUnique({ where: { email: 'test@example.com' } });
+    expect(user).not.toBeNull();
+  });
+
+  it('rejects invalid email', async () => {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ email: 'invalid', name: 'Test' }),
+    });
+    expect(res.status).toBe(400);
+  });
+});
+```
+
+## E2E Tests
+
+```typescript
+// tests/e2e/auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('user can sign up and access dashboard', async ({ page }) => {
+  await page.goto('/signup');
+  await page.fill('[name="email"]', 'new@example.com');
+  await page.fill('[name="password"]', 'securePassword123');
+  await page.click('button[type="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('h1')).toContainText('Welcome');
+});
+```
+
+## Coverage Targets
+
+- Business logic: >80%
+- API routes: >70%
+- UI components: >60%
+- E2E critical paths: 100%
+
+## What to Test
+
+- Happy path (it works)
+- Edge cases (empty, null, max values)
+- Error handling (invalid input, network failure)
+- Authorization (can't access others' data)
+
+## What NOT to Test
+
+- Third-party libraries (Stripe, NextAuth)
+- Framework internals
+- Trivial getters/setters

package/assets/cursor-rules/07-security.mdc

@@ -0,0 +1,94 @@
+# Security Rules
+
+## Environment Variables
+
+```bash
+# .env.local (NEVER commit)
+DATABASE_URL="postgresql://..."
+NEXTAUTH_SECRET="..." # openssl rand -base64 32
+STRIPE_SECRET_KEY="sk_..."
+STRIPE_WEBHOOK_SECRET="whsec_..."
+```
+
+- Use `.env.example` with placeholder values
+- Rotate secrets on any suspected breach
+- Different secrets per environment
+
+## Input Validation
+
+ALWAYS validate at API boundary:
+
+```typescript
+// Zod schema
+const userInput = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(1).max(100).trim(),
+  bio: z.string().max(1000).optional(),
+});
+```
+
+## SQL Injection Prevention
+
+- Use Prisma (parameterized queries by default)
+- Never interpolate user input into raw SQL
+
+```typescript
+// NEVER do this
+await prisma.$queryRaw`SELECT * FROM users WHERE id = ${userId}`;
+
+// Do this instead
+await prisma.user.findUnique({ where: { id: userId } });
+```
+
+## XSS Prevention
+
+- React escapes by default
+- Never use `dangerouslySetInnerHTML` with user content
+- Sanitize HTML if needed: `DOMPurify.sanitize(userHtml)`
+
+## CSRF Protection
+
+- NextAuth includes CSRF tokens
+- For custom forms, use `next-csrf` or similar
+
+## Rate Limiting
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 req/min
+});
+
+// In API route
+const { success } = await ratelimit.limit(ip);
+if (!success) {
+  return Response.json({ error: 'Rate limited' }, { status: 429 });
+}
+```
+
+## Authorization Checklist
+
+- [ ] Verify user is authenticated
+- [ ] Verify user owns the resource
+- [ ] Verify user has required role/permission
+- [ ] Log access attempts
+
+## Headers (Next.js)
+
+```typescript
+// next.config.js
+const securityHeaders = [
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+];
+```
+
+## Secrets in Code
+
+- Never hardcode secrets
+- Use `process.env` only on server
+- Audit with `gitleaks` or similar

package/assets/cursor-rules/08-deployment.mdc

@@ -0,0 +1,92 @@
+# Deployment Rules
+
+## Platform: Vercel (or specified)
+
+## Environment Setup
+
+```
+Production:  main branch → vercel.com/project
+Staging:     staging branch → staging.project.com
+Preview:     PR branches → pr-123.project.vercel.app
+```
+
+## Environment Variables
+
+Set in Vercel Dashboard:
+- `DATABASE_URL` - Production DB connection
+- `NEXTAUTH_URL` - Full production URL
+- `NEXTAUTH_SECRET` - Production secret
+- `STRIPE_SECRET_KEY` - Live key (not test!)
+- `STRIPE_WEBHOOK_SECRET` - Production webhook secret
+
+## Pre-Deploy Checklist
+
+- [ ] All tests pass (`npm test`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] No TypeScript errors
+- [ ] No console.log in production code
+- [ ] Environment variables set
+- [ ] Database migrations applied
+
+## Database Migrations
+
+```bash
+# Generate migration
+npx prisma migrate dev --name add_feature
+
+# Apply to production (in CI/CD)
+npx prisma migrate deploy
+```
+
+## CI/CD Pipeline (GitHub Actions)
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+          vercel-args: '--prod'
+```
+
+## Rollback Strategy
+
+- Vercel: Instant rollback via dashboard
+- Database: Keep migration rollback scripts
+- Feature flags: Disable without deploy
+
+## Monitoring Post-Deploy
+
+- Check error rates (Sentry, Vercel)
+- Check performance (Vercel Analytics)
+- Test critical user flows manually
+- Monitor webhooks (Stripe dashboard)
+
+## Domain Setup
+
+1. Add custom domain in Vercel
+2. Update DNS (CNAME or A record)
+3. Wait for SSL certificate
+4. Update `NEXTAUTH_URL` env var

package/assets/cursor-rules/09-error-handling.mdc

@@ -0,0 +1,137 @@
+# Error Handling Rules
+
+## Principle
+
+Never swallow errors. Always log, always handle, always inform.
+
+## API Error Format
+
+```typescript
+interface ApiError {
+  error: {
+    code: string;      // Machine-readable: 'VALIDATION_ERROR'
+    message: string;   // Human-readable: 'Email is required'
+    details?: any;     // Optional: field-level errors
+  };
+}
+```
+
+## Error Codes
+
+```typescript
+const ErrorCodes = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,        // Duplicate resource
+  RATE_LIMITED: 429,
+  INTERNAL_ERROR: 500,
+} as const;
+```
+
+## API Route Pattern
+
+```typescript
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const data = schema.parse(body);
+    const result = await service.create(data);
+    return Response.json({ data: result }, { status: 201 });
+  } catch (error) {
+    return handleApiError(error);
+  }
+}
+
+function handleApiError(error: unknown) {
+  if (error instanceof ZodError) {
+    return Response.json({
+      error: { code: 'VALIDATION_ERROR', message: 'Invalid input', details: error.errors }
+    }, { status: 400 });
+  }
+
+  if (error instanceof NotFoundError) {
+    return Response.json({
+      error: { code: 'NOT_FOUND', message: error.message }
+    }, { status: 404 });
+  }
+
+  // Log unexpected errors
+  console.error('Unexpected error:', error);
+
+  return Response.json({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }
+  }, { status: 500 });
+}
+```
+
+## Client-Side Error Handling
+
+```typescript
+async function createTask(data: TaskInput) {
+  const res = await fetch('/api/tasks', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  });
+
+  if (!res.ok) {
+    const { error } = await res.json();
+    throw new ApiError(error.code, error.message);
+  }
+
+  return res.json();
+}
+
+// In component
+try {
+  await createTask(data);
+  toast.success('Task created');
+} catch (error) {
+  if (error instanceof ApiError) {
+    toast.error(error.message);
+  } else {
+    toast.error('Something went wrong');
+  }
+}
+```
+
+## Error Boundaries (React)
+
+```typescript
+'use client';
+
+export function ErrorBoundary({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div className="error-container">
+      <h2>Something went wrong</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Logging
+
+```typescript
+// Use structured logging
+console.error(JSON.stringify({
+  level: 'error',
+  message: error.message,
+  stack: error.stack,
+  userId: session?.user?.id,
+  requestId: req.headers.get('x-request-id'),
+  timestamp: new Date().toISOString(),
+}));
+```
+
+## Sentry Integration
+
+```typescript
+// sentry.client.config.ts
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  tracesSampleRate: 0.1,
+  ignoreErrors: ['AbortError', 'Network request failed'],
+});
+```

package/assets/cursor-rules/10-performance.mdc

@@ -0,0 +1,123 @@
+# Performance Rules
+
+## Targets
+
+- Time to First Byte (TTFB): <200ms
+- Largest Contentful Paint (LCP): <2.5s
+- First Input Delay (FID): <100ms
+- Cumulative Layout Shift (CLS): <0.1
+- Lighthouse Score: >90
+
+## Next.js Optimizations
+
+### Images
+
+```typescript
+import Image from 'next/image';
+
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority // For above-the-fold images
+/>
+```
+
+### Fonts
+
+```typescript
+// app/layout.tsx
+import { Inter } from 'next/font/google';
+
+const inter = Inter({ subsets: ['latin'], display: 'swap' });
+```
+
+### Dynamic Imports
+
+```typescript
+import dynamic from 'next/dynamic';
+
+const HeavyChart = dynamic(() => import('@/components/Chart'), {
+  loading: () => <Skeleton />,
+  ssr: false, // Client-only if needed
+});
+```
+
+## Database Performance
+
+### Indexes
+
+```prisma
+model Task {
+  id        String @id
+  userId    String
+  status    String
+  createdAt DateTime
+
+  @@index([userId, status]) // Composite index for common queries
+  @@index([createdAt])      // For sorting
+}
+```
+
+### Query Optimization
+
+```typescript
+// BAD: N+1 query
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const tasks = await prisma.task.findMany({ where: { userId: user.id } });
+}
+
+// GOOD: Include relation
+const users = await prisma.user.findMany({
+  include: { tasks: true },
+});
+```
+
+### Pagination
+
+```typescript
+const tasks = await prisma.task.findMany({
+  where: { userId },
+  take: 20,
+  skip: page * 20,
+  orderBy: { createdAt: 'desc' },
+});
+```
+
+## Caching
+
+### React Query
+
+```typescript
+const { data } = useQuery({
+  queryKey: ['tasks', userId],
+  queryFn: fetchTasks,
+  staleTime: 5 * 60 * 1000, // 5 minutes
+});
+```
+
+### API Response Caching
+
+```typescript
+// For public data
+export async function GET() {
+  const data = await fetchData();
+  return Response.json(data, {
+    headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300' },
+  });
+}
+```
+
+## Bundle Size
+
+- Use `next/bundle-analyzer`
+- Tree-shake unused code
+- Import only what you need: `import { format } from 'date-fns'`
+
+## Monitoring
+
+- Vercel Analytics (Web Vitals)
+- Sentry Performance
+- Custom timing with `performance.mark()`