nextjs-hackathon-stack 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "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/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/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/AGENTS.md

@@ -19,3 +19,11 @@ Read `.env.example` for the full list. Key vars:
 - `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

@@ -7,6 +7,7 @@ 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
 

package/template/package.json.tmpl

@@ -17,6 +17,7 @@
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
     "db:push": "drizzle-kit push",
+    "db:pull": "drizzle-kit pull",
     "db:studio": "drizzle-kit studio",
     "prepare": "husky"
   },

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();
   });
 });