nextjs-hackathon-stack 0.1.0

package/template/.cursor/skills/create-feature/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: create-feature
+description: Scaffold a new feature following TDD and project conventions. Use when starting a new feature or user story.
+---
+
+# Create Feature Skill
+
+## Process
+
+### 1. Requirements First
+- Check `.requirements/` for existing spec
+- If none exists, ask the user to describe the feature
+- Document in `.requirements/<feature-name>.md` using the Given/When/Then template
+
+### 2. Create Feature Structure
+```
+src/features/<feature-name>/
+├── components/
+├── actions/
+├── hooks/
+├── api/
+└── __tests__/
+```
+
+### 3. TDD: RED Phase
+Write ALL test files first:
+- `__tests__/<component>.test.tsx` — component tests
+- `__tests__/use-<feature>.test.ts` — hook tests
+- `__tests__/<action>.test.ts` — action tests
+
+Run `npm run test:unit` — all tests must FAIL (RED).
+
+### 4. TDD: GREEN Phase
+Implement minimum code to pass each test:
+- Components → actions → hooks → API routes
+
+Run `npm run test:unit` — all tests must PASS (GREEN).
+
+### 5. Refactor
+Clean up while keeping tests green.
+
+### 6. Verify
+```bash
+npm run test:coverage   # Must show 100%
+npm run lint            # Must pass with 0 warnings
+npm run typecheck       # Must pass with 0 errors
+```
+
+## Guardrails
+- NEVER start implementation before tests exist
+- 100% coverage before marking done
+- Follow `features/* → shared/*` dependency direction

package/template/.cursor/skills/review-branch/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: review-branch
+description: Review current branch changes against develop. Runs full code quality checklist.
+disable-model-invocation: true
+---
+
+# Review Branch Skill
+
+## Process
+
+### 1. Get Changes
+```bash
+git diff develop...HEAD
+```
+Or for a specific branch:
+```bash
+git diff develop...<branch-name>
+```
+
+### 2. Check Each Changed File Against:
+
+#### Code Quality
+- Zero `any` types
+- Zero comments
+- Functions ≤ 20 lines, files ≤ 200 lines
+- No magic numbers/strings
+
+#### Tests
+- Test files exist for every changed source file
+- Tests cover new code paths
+- No implementation-detail testing
+
+#### Architecture
+- Correct imports (features → shared only)
+- Server Actions for mutations
+- Edge runtime on AI routes
+
+#### Security
+- Input validation at boundaries
+- Auth checks present
+- No exposed secrets
+
+### 3. Generate Report
+```
+## Branch Review: <branch-name>
+
+### Changed Files
+- [list each file]
+
+### Issues Found
+- [file:line]: [issue] → [fix]
+
+### Verdict: PASS / FAIL
+```
+
+### 4. Run Automated Checks
+```bash
+npm run lint
+npm run typecheck
+npm run test:coverage
+```

package/template/.cursor/skills/security-audit/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: security-audit
+description: Run a security audit on the codebase. Checks OWASP Top 10, RLS, secrets, and dependencies.
+disable-model-invocation: true
+---
+
+# Security Audit Skill
+
+## Process
+
+### 1. Dependency Audit
+```bash
+npm audit
+```
+Categorize findings by: Critical / High / Medium / Low
+
+### 2. Secret Scan
+Search for hardcoded secrets:
+```bash
+grep -r "sk_" src/ --include="*.ts"
+grep -r "apiKey\s*=" src/ --include="*.ts"
+grep -r "password\s*=" src/ --include="*.ts"
+```
+Check `.env.example` has no real values.
+
+### 3. RLS Verification
+For each table in `src/shared/db/schema.ts`:
+- Confirm RLS is enabled in Supabase dashboard
+- Confirm explicit policies exist
+
+### 4. Auth Coverage
+- Verify `middleware.ts` protects all non-public routes
+- Check every `route.ts` in protected features has auth check
+- Verify `app/(protected)/layout.tsx` has server-side auth check
+
+### 5. Input Validation
+- Every `route.ts` has Zod schema validation
+- Every `.action.ts` has Zod schema validation
+
+### 6. XSS Check
+```bash
+grep -r "dangerouslySetInnerHTML" src/ --include="*.tsx"
+```
+
+### 7. Security Headers
+Verify in `next.config.ts`:
+- `Content-Security-Policy`
+- `Strict-Transport-Security`
+- `X-Frame-Options`
+
+## Output Format
+```
+## Security Audit Report
+
+### Critical 🔴
+[findings]
+
+### High 🟠
+[findings]
+
+### Medium 🟡
+[findings]
+
+### Low 🟢
+[findings]
+
+### Passed ✅
+[clean checks]
+```

package/template/.env.example

@@ -0,0 +1,24 @@
+# =============================================================================
+# REQUIRED — fill these in before running npm run dev
+# =============================================================================
+
+# Supabase — https://supabase.com > Project Settings > API
+NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+
+# Supabase DB — https://supabase.com > Project Settings > Database > Connection string (URI)
+DATABASE_URL=postgresql://postgres:[password]@db.your-project-id.supabase.co:5432/postgres
+
+# MiniMax — https://www.minimaxi.chat > API Keys
+MINIMAX_API_KEY=your-minimax-api-key
+
+# Vercel AI Gateway — https://vercel.com > AI > Gateways
+# Format: https://gateway.ai.vercel.app/v1/{team-id}/{gateway-id}
+AI_GATEWAY_URL=https://gateway.ai.vercel.app/v1/your-team-id/your-gateway-id
+
+# =============================================================================
+# OPTIONAL
+# =============================================================================
+
+# App URL (used for OAuth callbacks)
+NEXT_PUBLIC_APP_URL=http://localhost:3000

package/template/.requirements/README.md

@@ -0,0 +1,15 @@
+# Requirements
+
+This directory contains feature requirements written in Given/When/Then format.
+
+## Structure
+- `README.md` — this file
+- `template.md` — requirement template
+- `auth.md` — authentication requirements
+- `<feature>.md` — per-feature requirements
+
+## Process
+1. Define requirements BEFORE starting implementation
+2. Each acceptance criterion maps to at least one test case
+3. Validate implementation against criteria before marking done
+4. Use the `business-intelligence` Cursor agent to help define requirements

package/template/.requirements/auth.md

@@ -0,0 +1,50 @@
+# Feature: Authentication
+
+## User Story
+As a user, I want to sign in with email and password so that I can access protected features.
+
+## Acceptance Criteria
+
+### AC1: Successful Login
+**Given** I am on the login page
+**When** I enter valid email and password
+**Then** I am redirected to the home page and my session is established
+
+### AC2: Invalid Credentials
+**Given** I am on the login page
+**When** I enter an incorrect email or password
+**Then** I see an error message "Invalid login credentials"
+
+### AC3: Validation Errors
+**Given** I am on the login page
+**When** I submit the form with an invalid email format
+**Then** I see "Invalid email" validation error before the form is submitted
+
+### AC4: Password Minimum Length
+**Given** I am on the login page
+**When** I enter a password shorter than 8 characters
+**Then** I see "Password must be at least 8 characters" error
+
+### AC5: Logout
+**Given** I am authenticated
+**When** I trigger logout
+**Then** My session is cleared and I am redirected to the login page
+
+### AC6: Protected Route Guard
+**Given** I am not authenticated
+**When** I navigate to any protected route
+**Then** I am redirected to the login page
+
+## Test Cases
+- [ ] TC1: Valid credentials → redirect to home
+- [ ] TC2: Wrong password → error message
+- [ ] TC3: Empty email → validation error
+- [ ] TC4: Invalid email format → validation error
+- [ ] TC5: Short password → validation error
+- [ ] TC6: Logout → redirect to login
+- [ ] TC7: Unauthenticated → redirect to login
+
+## Out of Scope
+- Social OAuth (Google, GitHub) — can be added later
+- Password reset flow — future enhancement
+- MFA — future enhancement

package/template/.requirements/template.md

@@ -0,0 +1,25 @@
+# Feature: [Feature Name]
+
+## User Story
+As a [user type], I want [goal] so that [reason].
+
+## Acceptance Criteria
+
+### AC1: [Scenario Name]
+**Given** [initial context]
+**When** [action taken]
+**Then** [expected outcome]
+
+### AC2: [Error Scenario]
+**Given** [initial context]
+**When** [invalid action]
+**Then** [error behavior]
+
+## Test Cases
+- [ ] TC1: [Happy path]
+- [ ] TC2: [Validation error]
+- [ ] TC3: [Auth error]
+- [ ] TC4: [Edge case]
+
+## Out of Scope
+- [What this feature does NOT cover]

package/template/README.md

@@ -0,0 +1,98 @@
+# {{projectName}}
+
+Full-stack Next.js 15 hackathon starter.
+
+## Stack
+
+| Layer | Tool |
+|---|---|
+| Framework | Next.js 15 + App Router |
+| Database | Supabase (PostgreSQL) |
+| Auth | Supabase Auth |
+| ORM | Drizzle (schema + migrations) |
+| Runtime Queries | supabase-js (RLS active) |
+| State | TanStack Query v5 |
+| Forms | React Hook Form + Zod |
+| UI | shadcn/ui + Tailwind CSS v4 |
+| AI | Vercel AI SDK + MiniMax |
+| Testing | Vitest + Playwright |
+
+## Getting Started
+
+### 1. Add your API keys
+
+`.env.local` was created automatically. Fill in the values:
+
+```bash
+# Supabase — https://supabase.com > Project Settings > API
+NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+DATABASE_URL=postgresql://postgres:[password]@db.your-project-id.supabase.co:5432/postgres
+
+# MiniMax — https://www.minimaxi.chat > API Keys
+MINIMAX_API_KEY=your-minimax-api-key
+
+# Vercel AI Gateway — https://vercel.com > AI > Gateways
+AI_GATEWAY_URL=https://gateway.ai.vercel.app/v1/your-team-id/your-gateway-id
+```
+
+### 2. Run the dev server
+
+```bash
+npm run dev
+```
+
+### 3. Apply database migrations
+
+```bash
+npm run db:generate
+npm run db:migrate
+```
+
+## Scripts
+
+```bash
+npm run dev          # Start dev server
+npm run build        # Production build
+npm run lint         # Lint (0 warnings allowed)
+npm run typecheck    # TypeScript check
+npm run test         # Unit tests
+npm run test:coverage # Tests with coverage (100% required)
+npm run test:e2e     # Playwright e2e tests
+npm run db:generate  # Generate Drizzle migrations
+npm run db:migrate   # Apply migrations
+```
+
+## Environment Variables
+
+| Variable | Where to get it |
+|---|---|
+| `NEXT_PUBLIC_SUPABASE_URL` | Supabase > Project Settings > API |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase > Project Settings > API |
+| `DATABASE_URL` | Supabase > Project Settings > Database > URI |
+| `MINIMAX_API_KEY` | minimaxi.chat > API Keys |
+| `AI_GATEWAY_URL` | Vercel > AI > Gateways |
+| `NEXT_PUBLIC_APP_URL` | Your deployment URL (default: `http://localhost:3000`) |
+
+See `.env.example` for all required variables with comments.
+
+## Architecture
+
+Feature-based structure:
+```
+src/
+├── app/           # Next.js routing + layouts
+├── features/      # auth | chat | video | tts
+├── shared/        # lib | db | components/ui
+└── e2e/           # Playwright tests
+```
+
+Dependency direction: `features/* → shared/*` (never reverse).
+
+## Cursor AI Setup
+
+Cursor rules, agents, and skills are preconfigured in `.cursor/`.
+
+- **Rules**: always-on guardrails for coding standards, architecture, security
+- **Agents**: specialized roles (technical-lead, frontend, test-qa, etc.)
+- **Skills**: repeatable workflows (`/create-feature`, `/create-api-route`, etc.)

package/template/components.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "slate",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/shared/components/ui",
+    "utils": "@/shared/lib/utils",
+    "ui": "@/shared/components/ui",
+    "lib": "@/shared/lib",
+    "hooks": "@/shared/hooks"
+  }
+}

package/template/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/shared/db/schema.ts",
+  out: "./src/shared/db/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env["DATABASE_URL"] ?? "",
+  },
+});

package/template/eslint.config.ts

@@ -0,0 +1,66 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import nextPlugin from "@next/eslint-plugin-next";
+import importPlugin from "eslint-plugin-import-x";
+import vitestPlugin from "eslint-plugin-vitest";
+import playwrightPlugin from "eslint-plugin-playwright";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      react: reactPlugin,
+      "react-hooks": reactHooksPlugin,
+      "@next/next": nextPlugin,
+      "import-x": importPlugin,
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-non-null-assertion": "error",
+      "no-console": "warn",
+      "react/react-in-jsx-scope": "off",
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "error",
+      "import-x/order": [
+        "error",
+        {
+          groups: ["builtin", "external", "internal", "parent", "sibling", "index"],
+          "newlines-between": "always",
+          alphabetize: { order: "asc" },
+        },
+      ],
+    },
+    settings: {
+      react: { version: "detect" },
+    },
+  },
+  {
+    files: ["**/*.test.ts", "**/*.test.tsx"],
+    plugins: { vitest: vitestPlugin },
+    rules: {
+      ...vitestPlugin.configs.recommended.rules,
+    },
+  },
+  {
+    files: ["src/e2e/**/*.spec.ts"],
+    plugins: { playwright: playwrightPlugin },
+    rules: {
+      ...playwrightPlugin.configs["flat/recommended"].rules,
+    },
+  },
+  {
+    ignores: [".next/**", "node_modules/**", "dist/**"],
+  }
+);

package/template/middleware.ts

@@ -0,0 +1,10 @@
+import { type NextRequest } from "next/server";
+import { updateSession } from "@/shared/lib/supabase/middleware";
+
+export async function middleware(request: NextRequest) {
+  return updateSession(request);
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"],
+};

package/template/next.config.ts

@@ -0,0 +1,31 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  experimental: {
+    typedRoutes: true,
+  },
+  headers: async () => [
+    {
+      source: "/(.*)",
+      headers: [
+        { key: "X-Frame-Options", value: "DENY" },
+        { key: "X-Content-Type-Options", value: "nosniff" },
+        { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+        { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" },
+        {
+          key: "Content-Security-Policy",
+          value: [
+            "default-src 'self'",
+            "script-src 'self' 'unsafe-eval' 'unsafe-inline'",
+            "style-src 'self' 'unsafe-inline'",
+            "img-src 'self' data: blob: https:",
+            "font-src 'self'",
+            "connect-src 'self' https://*.supabase.co wss://*.supabase.co",
+          ].join("; "),
+        },
+      ],
+    },
+  ],
+};
+
+export default nextConfig;

package/template/package.json.tmpl

@@ -0,0 +1,62 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run --reporter=verbose",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "next": "^15",
+    "@supabase/supabase-js": "^2",
+    "@supabase/ssr": "^0",
+    "drizzle-orm": "^0.45",
+    "drizzle-zod": "^0.7",
+    "@tanstack/react-query": "^5",
+    "ai": "^4",
+    "@ai-sdk/react": "^1",
+    "react-hook-form": "^7",
+    "@hookform/resolvers": "^3",
+    "zod": "^3",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "@types/node": "^22",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "drizzle-kit": "^0.30",
+    "vitest": "^3",
+    "@vitejs/plugin-react": "latest",
+    "@testing-library/react": "^16",
+    "@testing-library/jest-dom": "latest",
+    "@testing-library/user-event": "latest",
+    "@vitest/coverage-v8": "latest",
+    "@playwright/test": "^1.49",
+    "tailwindcss": "^4",
+    "@tailwindcss/postcss": "^4",
+    "postcss": "^8",
+    "eslint": "^9",
+    "@eslint/js": "^9",
+    "typescript-eslint": "^8",
+    "@next/eslint-plugin-next": "^15",
+    "eslint-plugin-react": "latest",
+    "eslint-plugin-react-hooks": "latest",
+    "eslint-plugin-import-x": "latest",
+    "eslint-plugin-vitest": "latest",
+    "eslint-plugin-playwright": "latest"
+  }
+}

package/template/playwright.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./src/e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env["CI"],
+  retries: process.env["CI"] ? 2 : 0,
+  workers: process.env["CI"] ? 1 : undefined,
+  reporter: "html",
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+  ],
+  webServer: {
+    command: "npm run dev",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env["CI"],
+  },
+});

package/template/src/app/(auth)/login/page.tsx

@@ -0,0 +1,12 @@
+import { LoginForm } from "@/features/auth/components/login-form";
+
+export default function LoginPage() {
+  return (
+    <main className="flex min-h-screen items-center justify-center">
+      <div className="w-full max-w-md p-8">
+        <h1 className="mb-8 text-2xl font-bold">Sign in</h1>
+        <LoginForm />
+      </div>
+    </main>
+  );
+}

package/template/src/app/(protected)/layout.tsx

@@ -0,0 +1,19 @@
+import { redirect } from "next/navigation";
+import { createClient } from "@/shared/lib/supabase/server";
+
+export default async function ProtectedLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const supabase = await createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+
+  if (!user) {
+    redirect("/login");
+  }
+
+  return <>{children}</>;
+}

package/template/src/app/(protected)/page.tsx

@@ -0,0 +1,16 @@
+import { createClient } from "@/shared/lib/supabase/server";
+import { ChatUi } from "@/features/chat/components/chat-ui";
+
+export default async function HomePage() {
+  const supabase = await createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+
+  return (
+    <main className="container mx-auto p-8">
+      <h1 className="mb-4 text-2xl font-bold">Welcome, {user?.email}</h1>
+      <ChatUi />
+    </main>
+  );
+}