nextjs-hackathon-stack 0.1.0

package/template/.cursor/rules/ai.mdc

@@ -0,0 +1,53 @@
+---
+description: AI SDK + Edge runtime rules. RISK 3 (cold starts).
+globs: ["src/features/chat/**", "src/features/video/**", "src/features/tts/**", "src/shared/lib/ai*"]
+---
+
+# AI Rules (Risk 3: Vercel Cold Starts)
+
+## Edge Runtime is Mandatory
+```typescript
+// ✅ ALL AI routes must export this
+export const runtime = "edge";
+
+// ❌ Never use Node.js runtime for AI routes (1-3s cold start)
+// export const runtime = "nodejs"; // WRONG
+```
+
+## Never Mix Edge + DB
+```typescript
+// ❌ WRONG — DB + Edge in same route
+export const runtime = "edge";
+import { db } from "@/shared/db"; // WRONG — postgres driver needs Node.js
+```
+
+If you need DB data in an AI route:
+1. Fetch DB data in a Server Component (Node.js)
+2. Pass to client
+3. Client sends to Edge AI route
+
+## AI Model via AI Gateway
+```typescript
+import { createOpenAI } from "@ai-sdk/openai";
+
+const gateway = createOpenAI({
+  baseURL: process.env.AI_GATEWAY_URL,
+  apiKey: process.env.MINIMAX_API_KEY,
+});
+
+export const aiModel = gateway("MiniMax-Text-01");
+```
+
+## Streaming Pattern
+```typescript
+import { streamText } from "ai";
+import { aiModel } from "@/shared/lib/ai";
+
+export const runtime = "edge";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const result = streamText({ model: aiModel, messages });
+  return result.toDataStreamResponse();
+}
+```

package/template/.cursor/rules/architecture.mdc

@@ -0,0 +1,42 @@
+---
+description: Feature-based architecture rules. Always applies.
+alwaysApply: true
+---
+
+# Architecture Rules
+
+## Feature-Based Structure
+```
+features/
+└── <feature-name>/
+    ├── components/     # React components
+    ├── actions/        # Server Actions (*.action.ts)
+    ├── hooks/          # React hooks (use-*.ts)
+    ├── api/            # Route handlers (route.ts)
+    └── __tests__/      # Colocated tests
+```
+
+## Dependency Direction
+```
+features/* → shared/*   ✅
+shared/* → features/*   ❌ (circular dependency)
+features/a → features/b ❌ (cross-feature import)
+```
+
+If two features share logic, move it to `shared/`.
+
+## Layer Rules
+- `app/` — routing, layouts, RSC data fetching
+- `features/` — feature business logic, UI, actions
+- `shared/lib/` — infrastructure (supabase, ai, db)
+- `shared/components/` — design system components
+
+## Error Boundaries
+- Place at route level (`app/(protected)/layout.tsx`)
+- Never let unhandled errors propagate to root
+
+## Server Actions
+- File naming: `name.action.ts`
+- Always `"use server"` at top of file
+- Validate input with Zod before any business logic
+- Return typed result objects, use `redirect()` for navigation

package/template/.cursor/rules/coding-standards.mdc

@@ -0,0 +1,53 @@
+---
+description: Code quality standards. Always applies to all files.
+alwaysApply: true
+---
+
+# Coding Standards
+
+## Absolute Rules
+- **Zero `any`** — use `unknown` + type guards or proper generics. `@typescript-eslint/no-explicit-any: error`
+- **Zero comments** — code must be self-documenting through naming. If you need a comment, rename the function
+- **Zero magic numbers/strings** — use typed constants
+- **No `console.log`** in production code — `no-console: warn`
+- **No `!` non-null assertions** — use proper null checks
+
+## TDD (Test-Driven Development)
+1. **RED**: Write a failing test first
+2. **GREEN**: Write minimum code to pass the test
+3. **REFACTOR**: Improve code while tests stay green
+
+Never write implementation before tests exist.
+
+## TDD — Iron Rule
+- Tests define the contract. **NEVER modify a test to make it pass.**
+- If a test fails, the implementation is wrong — fix the code, not the test.
+- Only modify tests to: add new tests (RED), restructure without weakening (REFACTOR).
+- Weakening a test (removing assertions, loosening matchers, adding `.skip`) is a rejection-worthy offense.
+
+## SOLID Principles
+- **S**ingle Responsibility: one reason to change per module
+- **O**pen/Closed: extend behavior without modifying existing code
+- **L**iskov Substitution: subtypes must be substitutable for base types
+- **I**nterface Segregation: prefer small, focused interfaces
+- **D**ependency Inversion: depend on abstractions, not concretions
+
+## KISS & DRY
+- Simplest solution that works — no over-engineering
+- Three similar lines is better than a premature abstraction
+- Extract abstraction only when you have 3+ real use cases
+
+## Size Limits
+- Functions: max 20 lines
+- Files: max 200 lines
+- If exceeded, split by responsibility
+
+## Error Handling
+- Use `Result` types for expected failures
+- Never swallow errors silently
+- Always handle Promise rejections
+
+## Types
+- Prefer `type` over `interface` for data shapes
+- Use `satisfies` for type-checked literals
+- Use `as const` for immutable literals

package/template/.cursor/rules/components.mdc

@@ -0,0 +1,33 @@
+---
+description: shadcn/ui and Tailwind v4 component standards.
+globs: ["src/**/components/**"]
+---
+
+# Component Standards
+
+## shadcn/ui
+- Use shadcn/ui components from `@/shared/components/ui/`
+- Never build custom UI primitives when shadcn has one
+- Extend with `className` prop via `cn()` utility
+- New York style, CSS variables for theming
+
+## Tailwind v4
+- CSS-native config via `@theme {}` in CSS
+- No `tailwind.config.js` — all config in `tailwind.css`
+- No inline styles, no CSS modules
+- Use Tailwind utility classes only
+
+## Accessibility (Required)
+- Semantic HTML elements (`<button>`, `<nav>`, `<main>`, etc.)
+- ARIA labels for interactive elements without visible text
+- Keyboard navigation support
+- Color contrast ratios (WCAG AA minimum)
+- `role="alert"` for error messages
+
+## Server vs Client Components
+- Default to Server Components (no `"use client"`)
+- Add `"use client"` only when you need:
+  - Event handlers (`onClick`, `onChange`, etc.)
+  - Hooks (`useState`, `useEffect`, etc.)
+  - Browser APIs
+- Keep Client Components small — push them to leaf nodes

package/template/.cursor/rules/data-fetching.mdc

@@ -0,0 +1,63 @@
+---
+description: TanStack Query vs RSC data fetching rules. RISK 1. Always applies.
+alwaysApply: true
+---
+
+# Data Fetching Rules (Risk 1: TanStack Query + RSC Boundary)
+
+## Hard Boundary
+
+| Use Case | Where |
+|---|---|
+| Initial page data | RSC `async` Server Component |
+| Background refresh / polling | TanStack Query |
+| User-triggered client reads | TanStack Query |
+| All mutations | Server Actions ONLY |
+
+**Never use TanStack Query mutations. Never use `useMutation`.**
+
+## WRONG ❌
+```typescript
+// ❌ Fetching initial data in a Client Component with TanStack Query
+"use client";
+export function UserProfile({ userId }: { userId: string }) {
+  const { data } = useQuery({
+    queryKey: ["user", userId],
+    queryFn: () => fetchUser(userId), // Initial data should come from RSC
+  });
+  return <div>{data?.name}</div>;
+}
+
+// ❌ Mutation with TanStack Query
+const mutation = useMutation({
+  mutationFn: (data) => updateUser(data), // Use Server Action instead
+});
+```
+
+## CORRECT ✅
+```typescript
+// ✅ Initial data from RSC, passed as prop
+export default async function UserPage({ params }: { params: { id: string } }) {
+  const user = await fetchUser(params.id); // RSC fetch
+  return <UserProfile initialUser={user} />;
+}
+
+// ✅ TanStack Query for background refresh only
+"use client";
+export function UserProfile({ initialUser }: { initialUser: User }) {
+  const { data: user } = useQuery({
+    queryKey: ["user", initialUser.id],
+    queryFn: () => fetchUser(initialUser.id),
+    initialData: initialUser, // Seeded from RSC
+    staleTime: 5 * 60 * 1000,
+  });
+  return <div>{user.name}</div>;
+}
+
+// ✅ Mutation via Server Action
+async function updateUserAction(formData: FormData) {
+  "use server";
+  await db.update(users).set({ name: formData.get("name") });
+  revalidatePath("/profile");
+}
+```

package/template/.cursor/rules/forms.mdc

@@ -0,0 +1,59 @@
+---
+description: React Hook Form + Server Actions pattern. RISK 4.
+globs: ["**/*form*", "**/*.action.ts"]
+---
+
+# Forms Pattern (Risk 4: RHF + Server Actions)
+
+## The One Pattern
+
+```
+Client: RHF + zodResolver → client validation (UX)
+     ↓ valid
+Server Action → zod validate again (security) → business logic
+```
+
+Zod validates TWICE:
+1. Client-side: immediate UX feedback via RHF
+2. Server-side: never trust the client
+
+## Template
+```typescript
+// form.tsx (client)
+"use client";
+const schema = z.object({ email: z.string().email() });
+type FormValues = z.infer<typeof schema>;
+
+export function MyForm() {
+  const [state, formAction, isPending] = useActionState(myAction, { status: "idle" });
+  const { register, handleSubmit, formState: { errors } } = useForm<FormValues>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = handleSubmit((data) => {
+    const fd = new FormData();
+    Object.entries(data).forEach(([k, v]) => fd.set(k, String(v)));
+    formAction(fd);
+  });
+
+  return (
+    <form onSubmit={onSubmit}>
+      {state.status === "error" && <p role="alert">{state.message}</p>}
+      <input {...register("email")} />
+      {errors.email && <p>{errors.email.message}</p>}
+      <button disabled={isPending}>Submit</button>
+    </form>
+  );
+}
+
+// action.ts (server)
+"use server";
+const schema = z.object({ email: z.string().email() });
+
+export async function myAction(_prev: State, formData: FormData): Promise<State> {
+  const parsed = schema.safeParse({ email: formData.get("email") });
+  if (!parsed.success) return { status: "error", message: parsed.error.issues[0]?.message ?? "Invalid" };
+  // business logic...
+  redirect("/success");
+}
+```

package/template/.cursor/rules/general.mdc

@@ -0,0 +1,52 @@
+---
+description: Stack overview and project conventions. Always applies.
+alwaysApply: true
+---
+
+# Stack Overview
+
+## Technology Stack
+- **Framework**: Next.js 15 (App Router)
+- **Database**: Supabase (PostgreSQL) with Drizzle ORM for schema/migrations
+- **Auth**: Supabase Auth via `@supabase/ssr`
+- **ORM**: Drizzle + `drizzle-zod` (schema + migrations ONLY — no runtime queries)
+- **DB Runtime Queries**: `supabase-js` client (RLS active)
+- **Client State**: TanStack Query v5
+- **Validation**: Zod (auto-generated via `drizzle-zod`)
+- **Forms**: React Hook Form + Zod resolver
+- **UI**: shadcn/ui + Tailwind CSS v4
+- **AI**: Vercel AI SDK + MiniMax M2.7 via AI Gateway
+- **Testing**: Vitest + React Testing Library + Playwright
+
+## Project Structure
+```
+src/
+├── app/               # Next.js App Router pages
+├── features/          # Feature modules (auth, chat, video, tts)
+│   └── <feature>/
+│       ├── components/
+│       ├── actions/
+│       ├── hooks/
+│       ├── api/
+│       └── __tests__/
+├── shared/            # Shared across features
+│   ├── components/ui/ # shadcn/ui components
+│   ├── lib/           # supabase, ai, utilities
+│   └── db/            # Drizzle schema + migrations
+└── e2e/               # Playwright tests
+```
+
+## Naming Conventions
+- Files: `kebab-case.ts`
+- Components: `PascalCase`
+- Hooks: `useCamelCase`
+- Server Actions: `camelCase.action.ts`
+- API Routes: `route.ts` (in feature `api/` folder)
+- Tests: `*.test.ts` or `*.test.tsx`
+- E2e: `*.spec.ts`
+
+## Import Ordering
+1. Node built-ins
+2. External packages
+3. Internal (`@/`)
+4. Relative (`./`, `../`)

package/template/.cursor/rules/nextjs.mdc

@@ -0,0 +1,46 @@
+---
+description: Next.js 15 App Router patterns.
+globs: ["src/app/**"]
+---
+
+# Next.js 15 Rules
+
+## App Router Conventions
+- `page.tsx` — public route page component
+- `layout.tsx` — shared layout (wraps child pages)
+- `loading.tsx` — Suspense boundary UI
+- `error.tsx` — Error boundary UI
+- `route.ts` — API route handler
+- `middleware.ts` — Edge middleware (project root)
+
+## Route Groups
+- `(auth)` — unauthenticated routes
+- `(protected)` — authenticated routes with RSC auth check
+
+## Data Fetching in RSC
+```typescript
+// ✅ Async Server Component — fetch directly
+export default async function Page() {
+  const data = await fetchData(); // No useState, no useEffect
+  return <ClientComponent initialData={data} />;
+}
+```
+
+## Route Handler Patterns
+```typescript
+// app/api/*/route.ts
+export async function POST(request: Request) {
+  const body = await request.json() as unknown;
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) return Response.json({ error: "Invalid input" }, { status: 400 });
+  // ...
+}
+```
+
+## Metadata
+```typescript
+export const metadata: Metadata = {
+  title: "Page Title",
+  description: "Page description",
+};
+```

package/template/.cursor/rules/security.mdc

@@ -0,0 +1,54 @@
+---
+description: Security rules and OWASP guidelines. Always applies.
+alwaysApply: true
+---
+
+# Security Rules
+
+## OWASP Top 10 Awareness
+1. **Injection** — use Drizzle parameterized queries, never string concatenation
+2. **Broken Auth** — Supabase Auth only, no custom auth
+3. **Sensitive Data** — HTTPS-only cookies, no secrets in code
+4. **XSS** — never use `dangerouslySetInnerHTML`, escape user input
+5. **Broken Access Control** — RLS on all tables, auth check in all protected routes
+6. **Security Misconfiguration** — CSP, HSTS, X-Frame-Options in `next.config.ts`
+7. **Insecure Dependencies** — run `npm audit` regularly
+8. **SSRF** — validate URLs before fetch
+
+## Environment Variables
+```
+NEXT_PUBLIC_*   → client-safe (Supabase URL, anon key only)
+No prefix       → server-only (DB URL, secret keys)
+```
+
+Never use `NEXT_PUBLIC_` for secret keys.
+
+## Supabase RLS
+- Enable RLS on EVERY table
+- Write explicit allow/deny policies
+- Test RLS policies — never assume they work
+
+## Auth in API Routes
+```typescript
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+  // ...
+}
+```
+
+## Input Validation
+- Validate ALL external input with Zod at the boundary
+- Validate in Server Actions AND API routes
+- Never trust client-side validation alone
+
+## Rate Limiting
+- Apply rate limiting to all AI routes
+- Apply rate limiting to auth endpoints
+- Use Vercel's built-in rate limiting or `@upstash/ratelimit`
+
+## Cookies
+- `httpOnly: true` for auth tokens (Supabase handles this)
+- `secure: true` in production
+- `sameSite: "lax"` minimum

package/template/.cursor/rules/supabase.mdc

@@ -0,0 +1,36 @@
+---
+description: Supabase + Drizzle rules. RISK 2 (schema drift).
+globs: ["src/shared/db/**", "src/shared/lib/supabase/**"]
+---
+
+# Supabase + Drizzle Rules (Risk 2: Zod Schema Drift)
+
+## Drizzle: Schema + Migrations ONLY
+```typescript
+// ✅ Use Drizzle for schema definition
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey(),
+  email: text("email").notNull(),
+});
+
+// ✅ Auto-generate Zod from Drizzle — zero manual Zod for DB types
+export const insertUserSchema = createInsertSchema(users);
+export const selectUserSchema = createSelectSchema(users);
+
+// ❌ NEVER write Zod schemas manually for DB types
+const userSchema = z.object({ id: z.string(), email: z.string() }); // WRONG
+```
+
+## Runtime Queries: supabase-js (RLS active)
+```typescript
+// ✅ Runtime queries via supabase-js
+const { data, error } = await supabase.from("users").select("*").eq("id", userId);
+
+// ❌ Never use Drizzle for runtime queries
+const users = await db.select().from(usersTable); // WRONG — bypasses RLS
+```
+
+## RLS Mandate
+- Enable RLS on ALL tables in Supabase dashboard
+- Every table must have explicit policies
+- Test RLS policies in migrations

package/template/.cursor/rules/testing.mdc

@@ -0,0 +1,116 @@
+---
+description: TDD, Vitest, and Playwright testing standards.
+globs: ["**/*.test.*", "**/e2e/**"]
+---
+
+# Testing Standards
+
+## Iron Rules (Non-Negotiable)
+1. **NEVER modify a test to make it pass** — always fix the implementation code. Tests define the contract. If a test fails, the code is wrong, not the test.
+2. **Tests are immutable during GREEN phase** — only modify tests in RED phase (writing new ones) or REFACTOR phase (improving structure, never weakening assertions)
+3. **100% branch coverage** — every `if`, `else`, `switch`, `??`, `?.`, ternary, and `catch` must be exercised
+4. **Every edge case gets a test** — null/undefined, empty string, empty array, boundary values, error responses, timeout, concurrent calls
+5. **AAA is mandatory** — every test uses Arrange-Act-Assert with labeled comments
+
+## TDD Cycle
+1. **RED**: Write failing test describing desired behavior
+2. **GREEN**: Write minimum code to make it pass
+3. **REFACTOR**: Clean up while keeping tests green
+
+## AAA Pattern (Arrange-Act-Assert)
+
+Every test MUST follow the Arrange-Act-Assert structure. No exceptions.
+
+```typescript
+it("shows error message on invalid credentials", async () => {
+  // Arrange
+  const user = userEvent.setup();
+  mockSignIn.mockResolvedValue({ error: { message: "Invalid credentials" } });
+  render(<LoginForm />);
+
+  // Act
+  await user.type(screen.getByLabelText(/email/i), "test@example.com");
+  await user.type(screen.getByLabelText(/password/i), "password123");
+  await user.click(screen.getByRole("button", { name: /sign in/i }));
+
+  // Assert
+  expect(await screen.findByRole("alert")).toHaveTextContent("Invalid credentials");
+});
+```
+
+Rules:
+- **Arrange**: set up state, mocks, render
+- **Act**: perform the single action being tested
+- **Assert**: verify outcome — one logical assertion per test
+- Add blank lines between sections when all three are non-trivial
+- Never skip a section — if Act is empty, you are testing the wrong thing
+
+## Vitest (Unit + Integration)
+- Mock external dependencies only (HTTP calls, Supabase, DB)
+- Test behavior, not implementation details
+- Colocate tests with source: `features/auth/__tests__/`
+- 100% coverage is non-negotiable
+
+```typescript
+// ✅ AAA — tests behavior
+it("shows error message on invalid credentials", async () => {
+  // Arrange
+  mockSignIn.mockResolvedValue({ error: { message: "Invalid credentials" } });
+  render(<LoginForm />);
+
+  // Act
+  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+
+  // Assert
+  expect(await screen.findByRole("alert")).toBeInTheDocument();
+});
+
+// ❌ No AAA — tests implementation details, brittle
+it("calls signInWithPassword with correct args", () => { ... });
+```
+
+## Playwright (E2E)
+- Use `data-testid` attributes for stable selectors
+- Page Object Pattern for complex flows
+- Every user flow needs an e2e test
+
+```typescript
+test("user can log in", async ({ page }) => {
+  // Arrange
+  await page.goto("/login");
+
+  // Act
+  await page.getByLabel(/email/i).fill("user@example.com");
+  await page.getByLabel(/password/i).fill("password123");
+  await page.getByRole("button", { name: /sign in/i }).click();
+
+  // Assert
+  await expect(page).toHaveURL("/");
+});
+```
+
+## Edge Case Checklist
+For every function, ask: what happens with...
+- null / undefined input
+- empty string / empty array / empty object
+- boundary values (0, -1, MAX_SAFE_INTEGER)
+- invalid types (wrong shape, missing fields)
+- API error responses (4xx, 5xx, network failure)
+- Loading / pending states
+- Concurrent calls / race conditions
+- Auth expired / missing session
+
+If any of these apply, write a test for it. No exceptions.
+
+## Coverage Thresholds
+```typescript
+// vitest.config.ts
+coverage: {
+  thresholds: {
+    branches: 100,
+    functions: 100,
+    lines: 100,
+    statements: 100,
+  },
+}
+```

package/template/.cursor/skills/create-api-route/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: create-api-route
+description: Create a new Next.js API route with validation, auth, and tests. Use when adding API endpoints to a feature.
+---
+
+# Create API Route Skill
+
+## Process
+
+### 1. Define Schema
+```typescript
+const requestSchema = z.object({ /* fields */ });
+const responseSchema = z.object({ /* fields */ });
+type RequestBody = z.infer<typeof requestSchema>;
+```
+
+### 2. Write Test First (TDD)
+```typescript
+describe("POST /api/my-route", () => {
+  it("returns 400 on invalid input", async () => { ... });
+  it("returns 401 when unauthenticated", async () => { ... });
+  it("returns 200 with valid input", async () => { ... });
+});
+```
+
+Run test — must FAIL (RED).
+
+### 3. Implement Route
+```typescript
+// Determine runtime:
+// - AI routes: export const runtime = "edge"
+// - DB routes: no export (Node.js default)
+
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+
+  const body = await request.json() as unknown;
+  const parsed = requestSchema.safeParse(body);
+  if (!parsed.success) return Response.json({ error: "Invalid input" }, { status: 400 });
+
+  // business logic...
+
+  return Response.json(result);
+}
+```
+
+### 4. Verify
+```bash
+npm run test:unit
+npm run lint
+npm run typecheck
+```
+
+## Checklist
+- [ ] Zod schema for request/response
+- [ ] Auth check (unless public endpoint)
+- [ ] Input validation
+- [ ] Correct runtime (`edge` for AI, `nodejs` default for DB)
+- [ ] Tests written BEFORE implementation
+- [ ] 100% coverage