project-mcp-server 2.0.0

package/skills/nextauth.md

@@ -0,0 +1,256 @@
+---
+name: nextauth
+description: "Activar cuando se configura o modifica autenticacion, se protegen rutas o layouts, o se trabaja con sesiones y roles"
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+# Skill: NextAuth.js v5 (beta 30)
+
+## Cuándo cargar esta skill
+- Configurar o modificar autenticación
+- Proteger rutas o layouts
+- Acceder a la sesión del usuario
+- Implementar middleware de auth
+- Manejar roles y permisos en rutas
+
+---
+
+## Configuración base (v5 beta 30)
+
+```typescript
+// lib/auth/config.ts
+import type { NextAuthConfig } from "next-auth"
+import Credentials from "next-auth/providers/credentials"
+import bcrypt from "bcrypt"
+import { prismaPostgres } from "@/lib/db/postgres"
+import { LoginSchema } from "@/types/schemas"
+
+export const authConfig: NextAuthConfig = {
+  providers: [
+    Credentials({
+      async authorize(credentials) {
+        const parsed = LoginSchema.safeParse(credentials)
+        if (!parsed.success) return null
+
+        const user = await prismaPostgres.user.findUnique({
+          where: { email: parsed.data.email },
+          select: { id: true, email: true, name: true, password: true, roleId: true }
+        })
+        if (!user) return null
+
+        const valid = await bcrypt.compare(parsed.data.password, user.password)
+        if (!valid) return null
+
+        // No retornar el password al cliente
+        const { password: _, ...safeUser } = user
+        return safeUser
+      }
+    })
+  ],
+
+  callbacks: {
+    // Extender el token JWT con datos del usuario
+    async jwt({ token, user }) {
+      if (user) {
+        token.id = user.id
+        token.roleId = user.roleId
+      }
+      return token
+    },
+    // Extender la sesión con datos del token
+    async session({ session, token }) {
+      if (token && session.user) {
+        session.user.id = token.id as string
+        session.user.roleId = token.roleId as string
+      }
+      return session
+    }
+  },
+
+  pages: {
+    signIn: "/login",
+    error: "/login"   // Redirigir errores al login
+  },
+
+  session: { strategy: "jwt" }
+}
+```
+
+```typescript
+// lib/auth/index.ts — exportar handlers y helper auth()
+import NextAuth from "next-auth"
+import { authConfig } from "./config"
+
+export const { handlers, auth, signIn, signOut } = NextAuth(authConfig)
+```
+
+```typescript
+// app/api/auth/[...nextauth]/route.ts
+import { handlers } from "@/lib/auth"
+export const { GET, POST } = handlers
+```
+
+---
+
+## Acceder a la sesión
+
+### En RSC o Server Actions
+```typescript
+import { auth } from "@/lib/auth"
+
+// En un RSC
+export default async function Page() {
+  const session = await auth()
+  if (!session) redirect("/login")
+
+  return <div>Hola {session.user.name}</div>
+}
+
+// En una Server Action
+export async function deletePost(id: string) {
+  "use server"
+  const session = await auth()
+  if (!session) throw new Error("Unauthorized")
+  if (session.user.roleId !== "admin") throw new Error("Forbidden")
+  // ...
+}
+```
+
+### En Client Components
+```typescript
+"use client"
+import { useSession } from "next-auth/react"
+
+export function UserMenu() {
+  const { data: session, status } = useSession()
+
+  if (status === "loading") return <Skeleton />
+  if (!session) return <LoginButton />
+
+  return <div>{session.user.name}</div>
+}
+```
+
+---
+
+## Middleware — protección de rutas
+
+```typescript
+// middleware.ts (raíz del proyecto)
+import { auth } from "@/lib/auth"
+import { NextResponse } from "next/server"
+
+export default auth((req) => {
+  const isLoggedIn = !!req.auth
+  const isOnDashboard = req.nextUrl.pathname.startsWith("/dashboard")
+  const isOnAdmin = req.nextUrl.pathname.startsWith("/admin")
+  const isOnLogin = req.nextUrl.pathname === "/login"
+
+  // Si intenta entrar al dashboard sin sesión → login
+  if (isOnDashboard && !isLoggedIn) {
+    return NextResponse.redirect(new URL("/login", req.url))
+  }
+
+  // Si intenta admin sin rol admin → 403
+  if (isOnAdmin) {
+    if (!isLoggedIn) return NextResponse.redirect(new URL("/login", req.url))
+    if (req.auth?.user?.roleId !== "admin") {
+      return NextResponse.redirect(new URL("/403", req.url))
+    }
+  }
+
+  // Si ya está logueado e intenta ir al login → dashboard
+  if (isOnLogin && isLoggedIn) {
+    return NextResponse.redirect(new URL("/dashboard", req.url))
+  }
+})
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/admin/:path*", "/login"]
+}
+```
+
+---
+
+## Extender tipos de sesión (TypeScript)
+
+```typescript
+// types/next-auth.d.ts
+import "next-auth"
+import "next-auth/jwt"
+
+declare module "next-auth" {
+  interface Session {
+    user: {
+      id: string
+      name: string
+      email: string
+      roleId: string
+    }
+  }
+
+  interface User {
+    roleId: string
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    id: string
+    roleId: string
+  }
+}
+```
+
+---
+
+## Login y logout desde Client Components
+
+```typescript
+"use client"
+import { signIn, signOut } from "next-auth/react"
+
+// Login con redirect
+<button onClick={() => signIn("credentials", { redirect: true, callbackUrl: "/dashboard" })}>
+  Iniciar sesión
+</button>
+
+// Logout
+<button onClick={() => signOut({ callbackUrl: "/login" })}>
+  Cerrar sesión
+</button>
+```
+
+---
+
+## Helper de permisos (RBAC)
+
+```typescript
+// lib/auth/permissions.ts
+import { auth } from "@/lib/auth"
+import { prismaPostgres } from "@/lib/db/postgres"
+
+export async function hasPermission(action: string): Promise<boolean> {
+  const session = await auth()
+  if (!session?.user?.roleId) return false
+
+  const permission = await prismaPostgres.permission.findFirst({
+    where: {
+      roleId: session.user.roleId,
+      action: { in: [action, `${action.split(":")[0]}:*`] }
+    }
+  })
+
+  return !!permission
+}
+
+// Uso en Server Action
+export async function createPost(data: unknown) {
+  "use server"
+  const allowed = await hasPermission("posts:create")
+  if (!allowed) throw new Error("Forbidden")
+  // ...
+}
+```

package/skills/nextjs.md

@@ -0,0 +1,262 @@
+---
+name: nextjs
+description: "Activar cuando se crean o modifican paginas, layouts, componentes React, Server Actions o Route Handlers en Next.js"
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+# Skill: Next.js 16 + React 19
+
+## Cuándo cargar esta skill
+- Crear o modificar páginas, layouts, o componentes React
+- Implementar Server Actions o Route Handlers
+- Trabajar con fetching de datos en RSC
+- Configurar metadata, loading, error boundaries
+- Cualquier tarea que involucre el App Router
+
+---
+
+## Decisión RSC vs Client Component
+
+```
+¿Necesita hooks (useState, useEffect, useRef)?     → "use client"
+¿Maneja eventos del DOM (onClick, onChange)?        → "use client"
+¿Usa Context de React?                              → "use client"
+¿Solo muestra datos / layout / estructura?          → RSC (default)
+¿Hace fetch de datos desde DB o API externa?        → RSC
+¿Necesita acceso a cookies/headers en runtime?      → RSC con cookies()/headers()
+```
+
+Regla práctica: empezar como RSC, agregar `"use client"` solo cuando el compilador
+o la lógica lo exija. Los Client Components deben ser hojas del árbol, no raíces.
+
+---
+
+## Patrones de data fetching (Next.js 16)
+
+### En RSC — fetch directo o query de DB
+```typescript
+// app/(dashboard)/users/page.tsx
+import { prismaPostgres } from "@/lib/db/postgres"
+
+export default async function UsersPage() {
+  // Directo — no hace falta useEffect ni SWR
+  const users = await prismaPostgres.user.findMany({
+    where: { active: true },
+    select: { id: true, name: true, email: true }
+  })
+
+  return <UserList users={users} />
+}
+```
+
+### Cache en RSC — usar `use cache` (Next 16, NO unstable_cache)
+```typescript
+import { unstable_cache as useCache } from "next/cache"
+
+// Revalidar cada hora, tag para invalidación manual
+const getProducts = useCache(
+  async () => prismaPostgres.product.findMany(),
+  ["products"],
+  { revalidate: 3600, tags: ["products"] }
+)
+
+// Invalidar desde Server Action
+import { revalidateTag } from "next/cache"
+revalidateTag("products")
+```
+
+---
+
+## Server Actions
+
+```typescript
+// server/actions/users.ts
+"use server"
+
+import { z } from "zod"
+import { prismaPostgres } from "@/lib/db/postgres"
+import { auth } from "@/lib/auth"
+
+const CreateUserSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  role: z.enum(["admin", "user"])
+})
+
+export async function createUser(formData: FormData) {
+  // 1. Autenticar
+  const session = await auth()
+  if (!session) throw new Error("Unauthorized")
+
+  // 2. Validar con Zod
+  const parsed = CreateUserSchema.safeParse({
+    name: formData.get("name"),
+    email: formData.get("email"),
+    role: formData.get("role")
+  })
+  if (!parsed.success) {
+    return { error: parsed.error.flatten().fieldErrors }
+  }
+
+  // 3. Ejecutar
+  const user = await prismaPostgres.user.create({ data: parsed.data })
+
+  // 4. Revalidar cache si aplica
+  revalidateTag("users")
+
+  return { success: true, user }
+}
+```
+
+### Consumir Server Action desde Client Component
+```typescript
+"use client"
+
+import { useActionState } from "react"  // React 19 — reemplaza useFormState
+import { createUser } from "@/server/actions/users"
+
+export function CreateUserForm() {
+  const [state, action, isPending] = useActionState(createUser, null)
+
+  return (
+    <form action={action}>
+      <input name="name" />
+      <input name="email" type="email" />
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Creando..." : "Crear usuario"}
+      </button>
+      {state?.error && <p>{JSON.stringify(state.error)}</p>}
+    </form>
+  )
+}
+```
+
+---
+
+## Route Handlers (API)
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from "next/server"
+import { auth } from "@/lib/auth"
+import { prismaPostgres } from "@/lib/db/postgres"
+
+export async function GET(request: NextRequest) {
+  const session = await auth()
+  if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
+
+  const { searchParams } = new URL(request.url)
+  const page = Number(searchParams.get("page") ?? 1)
+
+  const users = await prismaPostgres.user.findMany({
+    skip: (page - 1) * 20,
+    take: 20
+  })
+
+  return NextResponse.json({ users, page })
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json()
+  // validar con Zod, crear, retornar
+}
+```
+
+---
+
+## Layouts y metadata
+
+```typescript
+// app/(dashboard)/layout.tsx
+import { auth } from "@/lib/auth"
+import { redirect } from "next/navigation"
+
+export default async function DashboardLayout({
+  children
+}: {
+  children: React.ReactNode
+}) {
+  const session = await auth()
+  if (!session) redirect("/login")
+
+  return (
+    <div className="flex min-h-screen">
+      <aside>...</aside>
+      <main className="flex-1">{children}</main>
+    </div>
+  )
+}
+
+// Metadata dinámica
+export async function generateMetadata({ params }: { params: { id: string } }) {
+  const user = await prismaPostgres.user.findUnique({ where: { id: params.id } })
+  return { title: user?.name ?? "Usuario" }
+}
+```
+
+---
+
+## React 19 — novedades a usar
+
+```typescript
+// use() — leer promesas y context en render
+import { use } from "react"
+
+function UserDetails({ promise }: { promise: Promise<User> }) {
+  const user = use(promise)  // Suspense-compatible
+  return <div>{user.name}</div>
+}
+
+// useOptimistic — updates optimistas
+import { useOptimistic } from "react"
+
+function LikeButton({ post }) {
+  const [optimisticLikes, addOptimisticLike] = useOptimistic(
+    post.likes,
+    (current, increment: number) => current + increment
+  )
+
+  async function handleLike() {
+    addOptimisticLike(1)
+    await likePost(post.id)
+  }
+}
+
+// useActionState — reemplaza useFormState de React DOM
+import { useActionState } from "react"
+```
+
+---
+
+## Anti-patrones a evitar
+
+```typescript
+// ❌ No mezclar lógica de servidor en Client Components
+"use client"
+const data = await fetch("/api/users")  // Error: await en cliente sin Suspense
+
+// ❌ No usar cookies()/headers() fuera de RSC o Route Handlers
+// (en Client Components no están disponibles)
+
+// ❌ No importar código de servidor en Client Components
+import { prismaPostgres } from "@/lib/db/postgres"  // Expone DB al cliente
+
+// ✓ Pasar datos como props desde RSC padre
+export default async function Page() {
+  const data = await getData()
+  return <ClientComponent initialData={data} />
+}
+```
+
+---
+
+## Comandos frecuentes
+
+```bash
+pnpm dev                     # dev con Turbopack
+pnpm build                   # build de producción
+pnpm lint                    # ESLint 9
+pnpm type-check              # tsc --noEmit
+```