nextjs-hackathon-stack 0.1.24 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Scaffold a full-stack Next.js hackathon starter",
   "type": "module",
   "bin": {

package/template/.cursor/agents/backend.md

@@ -0,0 +1,83 @@
+---
+name: backend
+description: Backend specialist for Node.js, Next.js server-side, Supabase RLS policies, and Drizzle ORM schema/migrations.
+model: inherit
+readonly: false
+---
+
+# Backend Agent
+
+## Responsibilities
+- Build Next.js Server Actions, API routes, and middleware
+- Define Drizzle ORM schemas and manage migrations via CLI
+- Configure Supabase RLS policies and auth flows
+- Select appropriate runtime (Edge vs Node.js)
+
+## Rules
+
+### Drizzle ORM — Schema Definition Only
+```typescript
+// ✅ Use Drizzle for schema definition
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  email: text("email").notNull().unique(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+});
+
+// ✅ Auto-generate Zod from Drizzle — never write Zod for DB types manually
+export const insertUserSchema = createInsertSchema(users);
+export const selectUserSchema = createSelectSchema(users);
+
+// ❌ NEVER use Drizzle for runtime queries — bypasses RLS
+const users = await db.select().from(usersTable); // WRONG
+```
+
+### Runtime Queries — supabase-js (RLS always active)
+```typescript
+// ✅ All runtime queries via supabase-js
+const { data, error } = await supabase.from("users").select("*").eq("id", userId);
+
+// ❌ NEVER use Drizzle for runtime queries
+```
+
+### Migration Workflow
+**NEVER create or edit files in `src/shared/db/migrations/` directly.**
+
+Always follow this workflow:
+1. Edit schema: `src/shared/db/schema.ts`
+2. Generate migration: `pnpm db:generate`
+3. Review the generated SQL in `src/shared/db/migrations/`
+4. Apply migration: `pnpm db:migrate`
+5. Dev shortcut (push without migration file): `pnpm db:push`
+
+### Supabase RLS
+- Enable RLS on ALL tables — no exceptions
+- Every table must have explicit `SELECT`, `INSERT`, `UPDATE`, `DELETE` policies
+- Use `auth.uid()` in policies to scope to the authenticated user
+
+### Server Actions
+```typescript
+// ✅ Mutations via Server Actions with Zod validation
+"use server";
+export async function createUser(formData: FormData) {
+  const parsed = insertUserSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) return { error: parsed.error.flatten() };
+  // ... supabase-js mutation
+}
+
+// ❌ Never expose DATABASE_URL to the client
+```
+
+### Environment Variables
+- `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_ANON_KEY` — client-safe
+- `DATABASE_URL` — server-only (Drizzle migrations only), NEVER prefix with `NEXT_PUBLIC_`
+
+### Runtime Selection
+- Default to **Node.js runtime** for Server Actions and API routes
+- Use **Edge runtime** only when latency is critical and no Node.js APIs are needed
+
+## Guardrails
+- Never write migration SQL directly — always use `pnpm db:generate`
+- Never expose `DATABASE_URL` to the browser
+- RLS policies are required before any table goes to production
+- Validate all mutation inputs with Zod on the server side

package/template/.cursor/agents/security-researcher.md

@@ -12,7 +12,7 @@ readonly: true
 ### Authentication & Authorization
 - [ ] Supabase RLS enabled on all tables
 - [ ] Auth check in every protected API route
-- [ ] Session validation in middleware
+- [ ] Session validation in proxy
 - [ ] No hardcoded credentials or API keys
 
 ### Input Validation

package/template/.cursor/agents/technical-lead.md

@@ -1,6 +1,6 @@
 ---
 name: technical-lead
-description: Architecture decisions, code review, and PR review. Use when planning features, reviewing PRs, or making architectural decisions about the codebase.
+description: Orchestrator and architecture owner. Receives all requests, delegates to specialist agents, and reviews architectural decisions.
 model: inherit
 readonly: false
 ---
@@ -8,29 +8,55 @@ readonly: false
 # Technical Lead Agent
 
 ## Responsibilities
+- Act as the default entry point for all requests
+- Classify requests and delegate to the appropriate specialist agent(s)
+- Launch multiple agents in parallel for cross-domain tasks
 - Validate architectural decisions against project conventions
-- Review code for SOLID, KISS, DRY principles
 - Ensure proper layer separation and no circular dependencies
 - Verify TDD compliance (tests exist before implementation)
 
-## Review Checklist
+## Orchestration
+
+The technical-lead is the orchestrator. Every request passes through here first. Delegate to the appropriate specialist based on domain:
+
+| Agent | Use when |
+|---|---|
+| `frontend` | UI components, pages, layouts, Tailwind, shadcn/ui, accessibility |
+| `backend` | Server Actions, API routes, Supabase RLS, Drizzle schema, migrations |
+| `business-intelligence` | Requirements definition, user stories, acceptance criteria |
+| `test-qa` | Writing tests, TDD workflow, coverage enforcement |
+| `code-reviewer` | Branch/PR review (readonly) |
+| `security-researcher` | Security audits, vulnerability scanning (readonly) |
+
+## Delegation Rules
+
+- **Single-domain** → delegate to the matching agent
+- **Cross-domain** → launch multiple agents in parallel (e.g., a new feature needs `business-intelligence` for requirements + `backend` for API + `frontend` for UI)
+- Always delegate code review to `code-reviewer` — do not duplicate its checklist here
+- Always delegate security audits to `security-researcher`
+- The technical-lead retains final say on all architectural decisions
+
+## Workflow Sequences
+
+### New feature
+`business-intelligence` → `test-qa` (RED) → `backend`/`frontend` (GREEN) → `code-reviewer` → `security-researcher`
+
+### Bug fix
+`test-qa` (reproduce with failing test) → `backend`/`frontend` (fix) → `code-reviewer`
+
+### Refactor
+`technical-lead` (plan) → `backend`/`frontend` (implement) → `test-qa` (verify) → `code-reviewer`
+
+## Architectural Review Checklist
+
 - [ ] Zero `any` types
-- [ ] Zero comments (code is self-documenting)
-- [ ] Functions ≤ 20 lines, files ≤ 200 lines
-- [ ] Tests exist and were written BEFORE implementation
-- [ ] Coverage is 100% on all new/changed files
-- [ ] No circular imports (features → shared, not reverse)
-- [ ] Proper error handling (no silent failures)
-- [ ] No magic numbers or strings
-- [ ] Tests were NOT weakened or modified to make code pass (check git diff for test changes alongside impl)
-- [ ] All branches covered (if/else, ternary, ??, catch)
-- [ ] Edge cases tested (null, empty, boundary, error, auth expired)
-- [ ] Every test follows AAA pattern with labeled comments
+- [ ] No circular imports (`features → shared`, not reverse)
+- [ ] Proper layer separation
+- [ ] Edge runtime on all AI routes (Risk 3)
+- [ ] TanStack Query is NOT used for mutations (Risk 1)
 
 ## Guardrails
 - Reject any PR without test coverage
 - Reject any `any` type usage
 - Reject implementations without prior test (TDD violation)
 - Enforce `features/* → shared/*` dependency direction
-- Verify Edge runtime on all AI routes (Risk 3)
-- Verify TanStack Query is NOT used for mutations (Risk 1)

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

@@ -6,7 +6,7 @@ alwaysApply: true
 # Stack Overview
 
 ## Technology Stack
-- **Framework**: Next.js 15 (App Router)
+- **Framework**: Next.js 16 (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)

package/template/.cursor/rules/migrations.mdc

@@ -0,0 +1,27 @@
+---
+description: Migration files are auto-generated by Drizzle CLI. NEVER create, edit, or delete them directly.
+globs: ["src/shared/db/migrations/**"]
+---
+
+# Migration Files — Generated Artifacts
+
+Files in `src/shared/db/migrations/` are **auto-generated** by the Drizzle CLI. Do not create, edit, or delete them by hand.
+
+## Correct Workflow
+
+1. **Edit the schema**: `src/shared/db/schema.ts`
+2. **Generate the migration**: `pnpm db:generate`
+3. **Review** the generated SQL file in `src/shared/db/migrations/`
+4. **Apply the migration**: `pnpm db:migrate`
+
+## Available CLI Commands
+
+| Command | Purpose |
+|---|---|
+| `pnpm db:generate` | Generate a new migration SQL file from schema changes |
+| `pnpm db:migrate` | Apply pending migrations to the database |
+| `pnpm db:push` | Push schema directly to DB (dev only, no migration file) |
+
+## Why
+
+Hand-editing migration files causes schema drift and breaks the migration history. The CLI is the only safe source of truth for migration SQL.

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

@@ -1,9 +1,9 @@
 ---
-description: Next.js 15 App Router patterns.
+description: Next.js 16 App Router patterns.
 globs: ["src/app/**"]
 ---
 
-# Next.js 15 Rules
+# Next.js 16 Rules
 
 ## App Router Conventions
 - `page.tsx` — public route page component
@@ -11,7 +11,7 @@ globs: ["src/app/**"]
 - `loading.tsx` — Suspense boundary UI
 - `error.tsx` — Error boundary UI
 - `route.ts` — API route handler
-- `middleware.ts` — Edge middleware (project root)
+- `proxy.ts` — Request proxy (project root, Node.js runtime)
 
 ## Route Groups
 - `(auth)` — unauthenticated routes

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

@@ -34,3 +34,8 @@ const users = await db.select().from(usersTable); // WRONG — bypasses RLS
 - Enable RLS on ALL tables in Supabase dashboard
 - Every table must have explicit policies
 - Test RLS policies in migrations
+
+## Environment Variables
+- `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_ANON_KEY` — client-safe, used in browser + server
+- `DATABASE_URL` — server-only, used by Drizzle for migrations (`drizzle.config.ts`)
+- See `.env.example` for all required variables

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

@@ -29,7 +29,7 @@ For each table in `src/shared/db/schema.ts`:
 - Confirm explicit policies exist
 
 ### 4. Auth Coverage
-- Verify `middleware.ts` protects all non-public routes
+- Verify `proxy.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
 

package/template/AGENTS.md

@@ -0,0 +1,29 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# Next.js: ALWAYS read docs before coding
+
+Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.
+
+<!-- END:nextjs-agent-rules -->
+
+# Environment variables
+
+Read `.env.example` for the full list. Key vars:
+
+| Variable | Visibility | Where to get it |
+|---|---|---|
+| `NEXT_PUBLIC_SUPABASE_URL` | Client + Server | Supabase > Project Settings > API |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Client + Server | Supabase > Project Settings > API |
+| `DATABASE_URL` | Server only | Supabase > Project Settings > Database > Connection string (Session mode) |
+
+- `NEXT_PUBLIC_*` vars are safe to expose to the browser — they are public by design
+- Never add `NEXT_PUBLIC_` prefix to secret keys (`DATABASE_URL`, `AI_API_KEY`)
+- `.env.local` is gitignored — never commit real credentials
+
+# Migrations
+
+Migration files in `src/shared/db/migrations/` are auto-generated. NEVER create, edit, or delete them directly.
+- Edit schema: `src/shared/db/schema.ts`
+- Generate migration: `pnpm db:generate`
+- Apply migration: `pnpm db:migrate`
+- Push schema (dev only): `pnpm db:push`

package/template/CLAUDE.md

@@ -0,0 +1,16 @@
+@AGENTS.md
+
+# Architecture
+
+Feature-based structure: `src/features/* → src/shared/*` (never reverse).
+
+- **Drizzle** = schema + migrations ONLY. Never use Drizzle for runtime queries.
+- **supabase-js** = all runtime queries. RLS is always active.
+- **Zod schemas** for DB types: auto-generate via `drizzle-zod`, never write manually.
+- **Migrations** are auto-generated — NEVER write/edit SQL files in `src/shared/db/migrations/` directly. Use `pnpm db:generate` + `pnpm db:migrate`.
+
+# Testing
+
+- 100% coverage required — `pnpm test:coverage` must pass
+- AAA pattern (Arrange / Act / Assert) in every test
+- Mock only external boundaries (Supabase, HTTP, DB) — never mock internal code

package/template/README.md

@@ -1,12 +1,12 @@
 # {{projectName}}
 
-Full-stack Next.js 15 hackathon starter.
+Full-stack Next.js 16 hackathon starter.
 
 ## Stack
 
 | Layer | Tool |
 |---|---|
-| Framework | Next.js 15 + App Router |
+| Framework | Next.js 16 + App Router |
 | Database | Supabase (PostgreSQL) |
 | Auth | Supabase Auth |
 | ORM | Drizzle (schema + migrations) |

package/template/next.config.ts

@@ -2,6 +2,9 @@ import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   typedRoutes: true,
+  logging: {
+    browserToTerminal: true,
+  },
   turbopack: {
     root: import.meta.dirname,
   },

package/template/package.json.tmpl

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "next dev",
     "build": "next build",
     "start": "next start",
     "lint": "eslint . --max-warnings 0",
@@ -21,7 +21,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "next": "^15",
+    "next": "^16.2",
     "@supabase/supabase-js": "^2",
     "@supabase/ssr": "^0.6",
     "drizzle-orm": "^0.44",
@@ -45,6 +45,7 @@
     "@types/node": "^22",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@next/env": "^16",
     "drizzle-kit": "^0.30",
     "vitest": "^3",
     "@vitejs/plugin-react": "^4",
@@ -60,7 +61,7 @@
     "eslint": "^9",
     "@eslint/js": "^9",
     "typescript-eslint": "^8",
-    "@next/eslint-plugin-next": "^15",
+    "@next/eslint-plugin-next": "^16",
     "eslint-plugin-react": "^7",
     "eslint-plugin-react-hooks": "^5",
     "eslint-plugin-import-x": "^4",

package/template/{middleware.ts → proxy.ts}

@@ -2,7 +2,7 @@ import type { NextRequest } from "next/server";
 
 import { updateSession } from "@/shared/lib/supabase/middleware";
 
-export async function middleware(request: NextRequest) {
+export async function proxy(request: NextRequest) {
   return updateSession(request);
 }
 

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

@@ -5,9 +5,9 @@ export default function LoginPage() {
     <main className="flex min-h-screen items-center justify-center bg-muted/40 px-4">
       <div className="w-full max-w-sm space-y-6">
         <div className="text-center">
-          <h1 className="text-3xl font-bold tracking-tight">Welcome back</h1>
+          <h1 className="text-3xl font-bold tracking-tight">Bienvenido de nuevo</h1>
           <p className="mt-2 text-sm text-muted-foreground">
-            Sign in to your account to continue
+            Inicia sesión en tu cuenta para continuar
           </p>
         </div>
         <LoginForm />

package/template/src/app/__tests__/login-page.test.tsx

@@ -8,12 +8,12 @@ vi.mock("@/features/auth/components/login-form", () => ({
 }));
 
 describe("LoginPage", () => {
-  it("renders the welcome heading", () => {
+  it("renders the welcome heading in Spanish", () => {
     // Arrange + Act
     render(<LoginPage />);
 
     // Assert
-    expect(screen.getByText(/welcome back/i)).toBeInTheDocument();
+    expect(screen.getByText(/bienvenido de nuevo/i)).toBeInTheDocument();
   });
 
   it("renders the LoginForm component", () => {
@@ -24,11 +24,11 @@ describe("LoginPage", () => {
     expect(screen.getByTestId("login-form")).toBeInTheDocument();
   });
 
-  it("renders the sign-in description", () => {
+  it("renders the sign-in description in Spanish", () => {
     // Arrange + Act
     render(<LoginPage />);
 
     // Assert
-    expect(screen.getByText(/sign in to your account/i)).toBeInTheDocument();
+    expect(screen.getByText(/inicia sesión en tu cuenta/i)).toBeInTheDocument();
   });
 });

package/template/src/shared/__tests__/{middleware.test.ts → proxy.test.ts}

@@ -7,16 +7,16 @@ vi.mock("@/shared/lib/supabase/middleware", () => ({
   updateSession: (...args: unknown[]): unknown => mockUpdateSession(...args),
 }));
 
-describe("middleware", () => {
+describe("proxy", () => {
   it("delegates to updateSession", async () => {
     // Arrange
     const mockResponse = new Response(null, { status: 200 });
     mockUpdateSession.mockResolvedValue(mockResponse);
-    const mod = await import("../../../middleware") as { middleware: (req: NextRequest) => Promise<Response> };
+    const mod = await import("../../../proxy") as { proxy: (req: NextRequest) => Promise<Response> };
     const req = new NextRequest("http://localhost/dashboard");
 
     // Act
-    const response = await mod.middleware(req);
+    const response = await mod.proxy(req);
 
     // Assert
     expect(mockUpdateSession).toHaveBeenCalledWith(req);
@@ -25,7 +25,7 @@ describe("middleware", () => {
 
   it("exports a matcher config", async () => {
     // Arrange + Act
-    const mod = await import("../../../middleware") as { config: { matcher: string[] } };
+    const mod = await import("../../../proxy") as { config: { matcher: string[] } };
 
     // Assert
     expect(mod.config.matcher).toBeDefined();