ultra-dex 2.2.1 → 3.2.0

package/assets/code-patterns/trpc-router.ts

@@ -0,0 +1,258 @@
+// Ultra-Dex Production Pattern: tRPC Router
+// Copy to server/routers/ directory
+
+import { z } from 'zod';
+import { TRPCError } from '@trpc/server';
+import { router, publicProcedure, protectedProcedure, adminProcedure } from '../trpc';
+import { prisma } from '@/lib/prisma';
+
+// =============================================================================
+// USER ROUTER
+// =============================================================================
+
+export const userRouter = router({
+  // Get current user profile
+  me: protectedProcedure.query(async ({ ctx }) => {
+    const user = await prisma.user.findUnique({
+      where: { clerkId: ctx.userId },
+      include: {
+        organizationMemberships: {
+          include: { organization: true },
+        },
+      },
+    });
+
+    if (!user) {
+      throw new TRPCError({ code: 'NOT_FOUND', message: 'User not found' });
+    }
+
+    return user;
+  }),
+
+  // Update current user profile
+  update: protectedProcedure
+    .input(
+      z.object({
+        name: z.string().min(2).optional(),
+        imageUrl: z.string().url().optional(),
+      })
+    )
+    .mutation(async ({ ctx, input }) => {
+      return prisma.user.update({
+        where: { clerkId: ctx.userId },
+        data: input,
+      });
+    }),
+
+  // List all users (admin only)
+  list: adminProcedure
+    .input(
+      z.object({
+        limit: z.number().min(1).max(100).default(50),
+        cursor: z.string().optional(),
+      })
+    )
+    .query(async ({ input }) => {
+      const users = await prisma.user.findMany({
+        take: input.limit + 1,
+        cursor: input.cursor ? { id: input.cursor } : undefined,
+        orderBy: { createdAt: 'desc' },
+      });
+
+      let nextCursor: string | undefined;
+      if (users.length > input.limit) {
+        const nextItem = users.pop();
+        nextCursor = nextItem!.id;
+      }
+
+      return { users, nextCursor };
+    }),
+});
+
+// =============================================================================
+// PROJECT ROUTER
+// =============================================================================
+
+export const projectRouter = router({
+  // List projects for current organization
+  list: protectedProcedure
+    .input(
+      z.object({
+        organizationId: z.string(),
+        status: z.enum(['ACTIVE', 'ARCHIVED', 'COMPLETED']).optional(),
+      })
+    )
+    .query(async ({ ctx, input }) => {
+      // Verify user has access to organization
+      const membership = await prisma.organizationMember.findFirst({
+        where: {
+          organizationId: input.organizationId,
+          user: { clerkId: ctx.userId },
+        },
+      });
+
+      if (!membership) {
+        throw new TRPCError({ code: 'FORBIDDEN', message: 'Access denied' });
+      }
+
+      return prisma.project.findMany({
+        where: {
+          organizationId: input.organizationId,
+          ...(input.status && { status: input.status }),
+        },
+        include: {
+          owner: { select: { name: true, imageUrl: true } },
+          _count: { select: { tasks: true } },
+        },
+        orderBy: { updatedAt: 'desc' },
+      });
+    }),
+
+  // Get single project
+  get: protectedProcedure
+    .input(z.object({ id: z.string() }))
+    .query(async ({ ctx, input }) => {
+      const project = await prisma.project.findUnique({
+        where: { id: input.id },
+        include: {
+          owner: true,
+          tasks: { orderBy: { createdAt: 'desc' } },
+          organization: true,
+        },
+      });
+
+      if (!project) {
+        throw new TRPCError({ code: 'NOT_FOUND' });
+      }
+
+      // Verify access
+      const membership = await prisma.organizationMember.findFirst({
+        where: {
+          organizationId: project.organizationId,
+          user: { clerkId: ctx.userId },
+        },
+      });
+
+      if (!membership) {
+        throw new TRPCError({ code: 'FORBIDDEN' });
+      }
+
+      return project;
+    }),
+
+  // Create project
+  create: protectedProcedure
+    .input(
+      z.object({
+        name: z.string().min(1).max(100),
+        description: z.string().max(500).optional(),
+        organizationId: z.string(),
+      })
+    )
+    .mutation(async ({ ctx, input }) => {
+      // Verify user has write access to organization
+      const membership = await prisma.organizationMember.findFirst({
+        where: {
+          organizationId: input.organizationId,
+          user: { clerkId: ctx.userId },
+          role: { in: ['OWNER', 'ADMIN', 'MEMBER'] },
+        },
+      });
+
+      if (!membership) {
+        throw new TRPCError({ code: 'FORBIDDEN' });
+      }
+
+      const user = await prisma.user.findUnique({
+        where: { clerkId: ctx.userId },
+      });
+
+      return prisma.project.create({
+        data: {
+          name: input.name,
+          description: input.description,
+          organizationId: input.organizationId,
+          ownerId: user!.id,
+        },
+      });
+    }),
+
+  // Update project
+  update: protectedProcedure
+    .input(
+      z.object({
+        id: z.string(),
+        name: z.string().min(1).max(100).optional(),
+        description: z.string().max(500).optional(),
+        status: z.enum(['ACTIVE', 'ARCHIVED', 'COMPLETED']).optional(),
+      })
+    )
+    .mutation(async ({ ctx, input }) => {
+      const { id, ...data } = input;
+
+      const project = await prisma.project.findUnique({
+        where: { id },
+      });
+
+      if (!project) {
+        throw new TRPCError({ code: 'NOT_FOUND' });
+      }
+
+      // Verify write access
+      const membership = await prisma.organizationMember.findFirst({
+        where: {
+          organizationId: project.organizationId,
+          user: { clerkId: ctx.userId },
+          role: { in: ['OWNER', 'ADMIN', 'MEMBER'] },
+        },
+      });
+
+      if (!membership) {
+        throw new TRPCError({ code: 'FORBIDDEN' });
+      }
+
+      return prisma.project.update({
+        where: { id },
+        data,
+      });
+    }),
+
+  // Delete project
+  delete: protectedProcedure
+    .input(z.object({ id: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const project = await prisma.project.findUnique({
+        where: { id: input.id },
+      });
+
+      if (!project) {
+        throw new TRPCError({ code: 'NOT_FOUND' });
+      }
+
+      // Only owner/admin can delete
+      const membership = await prisma.organizationMember.findFirst({
+        where: {
+          organizationId: project.organizationId,
+          user: { clerkId: ctx.userId },
+          role: { in: ['OWNER', 'ADMIN'] },
+        },
+      });
+
+      if (!membership) {
+        throw new TRPCError({ code: 'FORBIDDEN' });
+      }
+
+      return prisma.project.delete({ where: { id: input.id } });
+    }),
+});
+
+// =============================================================================
+// ROOT ROUTER
+// =============================================================================
+
+export const appRouter = router({
+  user: userRouter,
+  project: projectRouter,
+});
+
+export type AppRouter = typeof appRouter;

package/assets/cursor-rules/13-ai-integration.mdc

@@ -0,0 +1,155 @@
+# AI/LLM Integration (2026 Patterns)
+
+> Patterns for integrating AI into production applications.
+
+## Vercel AI SDK (Recommended)
+
+```tsx
+// app/api/chat/route.ts
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: anthropic('claude-sonnet-4-20250514'),
+    messages,
+    system: 'You are a helpful assistant.',
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+## Client-Side Streaming
+
+```tsx
+'use client';
+
+import { useChat } from 'ai/react';
+
+export function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+          disabled={isLoading}
+        />
+        <button type="submit" disabled={isLoading}>
+          {isLoading ? 'Thinking...' : 'Send'}
+        </button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Structured Output with Zod
+
+```tsx
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const ProductSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  price: z.number(),
+  category: z.enum(['electronics', 'clothing', 'food']),
+});
+
+const { object } = await generateObject({
+  model: anthropic('claude-sonnet-4-20250514'),
+  schema: ProductSchema,
+  prompt: 'Generate a product for an e-commerce store.',
+});
+
+// object is fully typed as { name: string, description: string, ... }
+```
+
+## Tool Use / Function Calling
+
+```tsx
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools: {
+    weather: tool({
+      description: 'Get the weather for a location',
+      parameters: z.object({
+        location: z.string().describe('City name'),
+      }),
+      execute: async ({ location }) => {
+        // Call weather API
+        return { temperature: 72, condition: 'sunny' };
+      },
+    }),
+  },
+  prompt: 'What is the weather in San Francisco?',
+});
+```
+
+## Rate Limiting for AI Endpoints
+
+```tsx
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 requests per minute
+});
+
+export async function POST(req: Request) {
+  const ip = req.headers.get('x-forwarded-for') ?? '127.0.0.1';
+  const { success } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new Response('Rate limit exceeded', { status: 429 });
+  }
+
+  // Process AI request...
+}
+```
+
+## Caching AI Responses
+
+```tsx
+import { unstable_cache } from 'next/cache';
+
+const getCachedSummary = unstable_cache(
+  async (documentId: string) => {
+    const result = await generateText({
+      model: anthropic('claude-sonnet-4-20250514'),
+      prompt: `Summarize document ${documentId}`,
+    });
+    return result.text;
+  },
+  ['document-summary'],
+  { revalidate: 3600 } // Cache for 1 hour
+);
+```
+
+## Rules
+
+- Always stream long responses (better UX)
+- Use structured output for data extraction
+- Implement rate limiting on AI endpoints
+- Cache deterministic AI responses
+- Handle errors gracefully (retries, fallbacks)
+- Log AI usage for cost monitoring
+- Use environment variables for API keys
+- Validate all AI outputs before using

package/assets/cursor-rules/14-server-components.mdc

@@ -0,0 +1,81 @@
+# Server Components (React 19 / Next.js 15)
+
+> Default to Server Components. Use Client Components only when necessary.
+
+## When to Use Server Components
+
+- Data fetching
+- Accessing backend resources directly
+- Keeping sensitive logic on server
+- Large dependencies that shouldn't be in client bundle
+- SEO-critical content
+
+## When to Use Client Components
+
+- Interactivity (onClick, onChange, etc.)
+- Browser APIs (localStorage, geolocation)
+- React hooks (useState, useEffect, useContext)
+- Third-party libraries that use browser APIs
+
+## Patterns
+
+### Data Fetching in Server Components
+
+```tsx
+// app/users/page.tsx (Server Component)
+import { prisma } from '@/lib/prisma';
+
+export default async function UsersPage() {
+  const users = await prisma.user.findMany({
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return (
+    <div>
+      {users.map(user => (
+        <UserCard key={user.id} user={user} />
+      ))}
+    </div>
+  );
+}
+```
+
+### Composition Pattern
+
+```tsx
+// Server Component wrapper
+async function UserList() {
+  const users = await getUsers();
+  return <UserListClient users={users} />;
+}
+
+// Client Component for interactivity
+'use client';
+function UserListClient({ users }) {
+  const [selected, setSelected] = useState(null);
+  return (/* interactive UI */);
+}
+```
+
+### Passing Server Data to Client
+
+```tsx
+// Server Component
+export default async function Page() {
+  const data = await fetchData(); // Server-side fetch
+
+  return (
+    <ClientComponent
+      initialData={data}  // Serializable data only
+    />
+  );
+}
+```
+
+## Rules
+
+- Never import Server Components into Client Components
+- Keep 'use client' boundary as low as possible
+- Don't pass functions as props across the boundary
+- Use Server Actions for mutations, not API routes
+- Async components are Server Components by default

package/assets/cursor-rules/15-server-actions.mdc

@@ -0,0 +1,102 @@
+# Server Actions (Next.js 15)
+
+> Use Server Actions for mutations. They replace API routes for form submissions.
+
+## Basic Pattern
+
+```tsx
+// app/actions.ts
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const schema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+});
+
+export async function createUser(formData: FormData) {
+  const data = schema.parse({
+    name: formData.get('name'),
+    email: formData.get('email'),
+  });
+
+  await db.user.create({ data });
+  revalidatePath('/users');
+}
+```
+
+## With useActionState (React 19)
+
+```tsx
+'use client';
+
+import { useActionState } from 'react';
+import { createUser } from './actions';
+
+type State = { error?: string; success?: boolean };
+
+export function Form() {
+  const [state, formAction, isPending] = useActionState<State, FormData>(
+    async (prevState, formData) => {
+      try {
+        await createUser(formData);
+        return { success: true };
+      } catch (e) {
+        return { error: e.message };
+      }
+    },
+    {}
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      {state.error && <p className="error">{state.error}</p>}
+      <button disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Validation Pattern
+
+```tsx
+'use server';
+
+type ActionResult<T = void> =
+  | { success: true; data: T }
+  | { success: false; error: string; fieldErrors?: Record<string, string[]> };
+
+export async function action(formData: FormData): Promise<ActionResult<{ id: string }>> {
+  const validated = schema.safeParse(Object.fromEntries(formData));
+
+  if (!validated.success) {
+    return {
+      success: false,
+      error: 'Validation failed',
+      fieldErrors: validated.error.flatten().fieldErrors,
+    };
+  }
+
+  try {
+    const result = await db.create({ data: validated.data });
+    return { success: true, data: { id: result.id } };
+  } catch {
+    return { success: false, error: 'Database error' };
+  }
+}
+```
+
+## Rules
+
+- Always use 'use server' directive
+- Validate ALL inputs with Zod
+- Return structured results, not throw errors
+- Use revalidatePath/revalidateTag for cache invalidation
+- Keep actions in separate files for organization
+- Actions can only receive serializable arguments

package/assets/cursor-rules/16-edge-middleware.mdc

@@ -0,0 +1,105 @@
+# Edge Middleware (Next.js 15)
+
+> Middleware runs before every request. Use for auth, redirects, and headers.
+
+## Basic Middleware
+
+```ts
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  // Check auth
+  const token = request.cookies.get('session')?.value;
+
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+## With Clerk Auth
+
+```ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isPublicRoute = createRouteMatcher(['/', '/sign-in(.*)', '/api/webhooks(.*)']);
+const isAdminRoute = createRouteMatcher(['/admin(.*)']);
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isPublicRoute(req)) return;
+
+  const { userId, sessionClaims } = await auth();
+
+  if (!userId) {
+    return Response.redirect(new URL('/sign-in', req.url));
+  }
+
+  if (isAdminRoute(req) && sessionClaims?.role !== 'admin') {
+    return Response.redirect(new URL('/unauthorized', req.url));
+  }
+});
+```
+
+## Geolocation & A/B Testing
+
+```ts
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country || 'US';
+  const response = NextResponse.next();
+
+  // Set header for downstream use
+  response.headers.set('x-user-country', country);
+
+  // A/B test assignment
+  const bucket = Math.random() < 0.5 ? 'control' : 'variant';
+  response.cookies.set('ab-bucket', bucket);
+
+  return response;
+}
+```
+
+## Rate Limiting Pattern
+
+```ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+});
+
+export async function middleware(request: NextRequest) {
+  const ip = request.ip ?? '127.0.0.1';
+  const { success, limit, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new NextResponse('Too Many Requests', {
+      status: 429,
+      headers: {
+        'X-RateLimit-Limit': limit.toString(),
+        'X-RateLimit-Remaining': remaining.toString(),
+      },
+    });
+  }
+
+  return NextResponse.next();
+}
+```
+
+## Rules
+
+- Middleware runs on Edge Runtime (limited Node.js APIs)
+- Keep middleware fast (<50ms)
+- Use matcher to limit which routes trigger middleware
+- Don't do heavy computation or database calls
+- Use for: auth, redirects, headers, A/B tests, geolocation
+- Avoid: data fetching, heavy validation, logging