project-mcp-server 2.0.0

package/skills/prisma.md

@@ -0,0 +1,281 @@
+---
+name: prisma
+description: "Activar cuando se modifican schemas de Prisma, se escriben queries de base de datos o se trabaja con migraciones"
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+# Skill: Prisma 7 — multi-schema
+
+## Cuándo cargar esta skill
+- Modificar o crear schemas de Prisma
+- Escribir queries de base de datos
+- Crear o correr migrations
+- Escribir seeds
+- Trabajar con el cliente PostgreSQL o MySQL
+
+---
+
+## Arquitectura de clientes
+
+Este proyecto tiene **dos conexiones** separadas:
+
+```typescript
+// lib/db/postgres.ts — cliente principal (auth, rbac, audit, base)
+import { PrismaClient } from "@prisma/client"
+import { PrismaPg } from "@prisma/adapter-pg"
+import { Pool } from "pg"
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+const adapter = new PrismaPg(pool)
+
+export const prismaPostgres = new PrismaClient({ adapter })
+
+// lib/db/mysql.ts — cliente secundario
+import { PrismaClient } from "@prisma/mysql-client"  // cliente generado para mysql
+import { createPool } from "mysql2/promise"
+import { PrismaMysql } from "@prisma/adapter-mysql"  // si aplica
+
+export const prismaMySQL = new PrismaClient(...)
+```
+
+**Regla**: siempre importar el cliente correcto según el dominio de la entidad.
+
+---
+
+## Estructura de schemas multi-schema
+
+```prisma
+// prisma/schema/auth.prisma
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["multiSchema"]
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+  schemas  = ["auth", "rbac", "audit", "base"]
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  password  String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@schema("auth")
+}
+
+model Session {
+  id           String   @id @default(cuid())
+  sessionToken String   @unique
+  userId       String
+  expires      DateTime
+  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@schema("auth")
+}
+```
+
+```prisma
+// prisma/schema/rbac.prisma
+model Role {
+  id          String       @id @default(cuid())
+  name        String       @unique
+  permissions Permission[]
+  users       UserRole[]
+
+  @@schema("rbac")
+}
+
+model Permission {
+  id     String @id @default(cuid())
+  action String  // ej: "users:create", "posts:delete"
+  roleId String
+  role   Role   @relation(fields: [roleId], references: [id])
+
+  @@schema("rbac")
+}
+```
+
+---
+
+## Queries con Prisma 7
+
+### Patrones correctos de selección
+```typescript
+// ✓ Siempre select explícito — nunca traer campos sensibles por defecto
+const user = await prismaPostgres.user.findUnique({
+  where: { id },
+  select: {
+    id: true,
+    email: true,
+    name: true,
+    // nunca incluir 'password' salvo en contexto de auth
+  }
+})
+
+// ✓ Include para relaciones — solo lo que se usa en la UI
+const userWithRoles = await prismaPostgres.user.findUnique({
+  where: { id },
+  include: {
+    roles: {
+      include: { permissions: true }
+    }
+  }
+})
+```
+
+### Queries cross-schema (dentro del mismo cliente PostgreSQL)
+```typescript
+// Las relaciones entre schemas se manejan en el schema de Prisma
+// En queries, se accede igual que cualquier relación
+const auditLogs = await prismaPostgres.auditLog.findMany({
+  where: { userId: user.id },
+  orderBy: { createdAt: "desc" },
+  take: 50
+})
+```
+
+### Transactions
+```typescript
+// Para operaciones atómicas entre tablas
+const result = await prismaPostgres.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: userData })
+  await tx.userRole.create({ data: { userId: user.id, roleId: defaultRoleId } })
+  await tx.auditLog.create({ data: { action: "user.created", userId: user.id } })
+  return user
+})
+```
+
+### Queries en MySQL (cliente secundario)
+```typescript
+import { prismaMySQL } from "@/lib/db/mysql"
+
+const records = await prismaMySQL.legacyRecord.findMany({
+  where: { status: "active" }
+})
+```
+
+---
+
+## Migrations
+
+```bash
+# Crear migration después de cambiar un schema
+pnpm prisma migrate dev --name nombre-descriptivo-en-snake-case
+
+# Ejemplos de nombres:
+# add-user-roles-table
+# add-email-verified-to-user
+# create-audit-schema
+# add-permissions-index
+
+# Aplicar en producción (no crea archivos, solo aplica pending)
+pnpm prisma migrate deploy
+
+# Reset completo (solo en dev)
+pnpm prisma migrate reset
+
+# Ver estado de migrations
+pnpm prisma migrate status
+```
+
+**Importante**: nunca editar archivos de migration ya aplicados. Si hay un error,
+crear una nueva migration que lo corrija.
+
+---
+
+## Seeds con tsx
+
+```typescript
+// prisma/seeds/roles.ts
+import { prismaPostgres } from "@/lib/db/postgres"
+
+const ROLES = [
+  {
+    name: "admin",
+    permissions: ["users:create", "users:delete", "users:read", "posts:*"]
+  },
+  {
+    name: "editor",
+    permissions: ["posts:create", "posts:update", "posts:read"]
+  },
+  {
+    name: "viewer",
+    permissions: ["posts:read", "users:read"]
+  }
+]
+
+async function seedRoles() {
+  console.log("Seeding roles...")
+
+  for (const roleData of ROLES) {
+    const role = await prismaPostgres.role.upsert({
+      where: { name: roleData.name },
+      update: {},
+      create: { name: roleData.name }
+    })
+
+    for (const action of roleData.permissions) {
+      await prismaPostgres.permission.upsert({
+        where: { roleId_action: { roleId: role.id, action } },
+        update: {},
+        create: { roleId: role.id, action }
+      })
+    }
+  }
+
+  console.log("✓ Roles seeded")
+}
+
+seedRoles()
+  .catch(console.error)
+  .finally(() => prismaPostgres.$disconnect())
+```
+
+```bash
+# Correr seed
+pnpm tsx prisma/seeds/roles.ts
+```
+
+---
+
+## Prisma Studio y herramientas
+
+```bash
+pnpm prisma studio           # UI visual para explorar datos (localhost:5555)
+pnpm prisma generate         # Regenerar cliente después de cambiar schema
+pnpm prisma db push          # Sync schema → DB sin migration (solo en dev)
+pnpm prisma validate         # Validar syntax del schema
+pnpm prisma format           # Formatear archivos .prisma
+```
+
+---
+
+## Anti-patrones a evitar
+
+```typescript
+// ❌ No hacer queries sin select — expone datos sensibles
+const user = await prismaPostgres.user.findUnique({ where: { id } })
+// Devuelve password hasheado y otros campos sensibles
+
+// ❌ No mezclar clientes — MySQL con entidades de PostgreSQL
+import { prismaMySQL } from "@/lib/db/mysql"
+const user = await prismaMySQL.user.findUnique(...)  // El modelo User es de PostgreSQL
+
+// ❌ No hardcodear IDs de roles o permisos — usar queries o constantes
+const adminRole = await prismaPostgres.role.findUnique({ where: { name: "admin" } })
+
+// ❌ No hacer N+1 queries — usar include o select con relaciones
+const users = await prismaPostgres.user.findMany()
+for (const user of users) {
+  // ❌ Query por cada usuario
+  const roles = await prismaPostgres.userRole.findMany({ where: { userId: user.id } })
+}
+// ✓ Un solo query con include
+const users = await prismaPostgres.user.findMany({ include: { roles: true } })
+```

package/skills/project-intelligence.SKILL.md

@@ -0,0 +1,141 @@
+---
+name: project-intelligence
+description: "Activar cuando se trabaja con SDD en un proyecto Next.js que tiene project-mcp-server configurado como MCP"
+license: MIT
+metadata:
+  version: "1.0.0"
+  author: "Fernando Secchi"
+---
+
+# Project Intelligence para SDD
+
+Integra el MCP `project-mcp-server` con el flujo SDD. Este MCP expone 10 tools que dan inteligencia real del proyecto: escaneo de rutas, Server Actions, modelos Prisma, componentes, y generación de código basada en el schema real.
+
+---
+
+## Cuándo cargar esta skill
+
+- Cuando se inicia un flujo SDD en un proyecto Next.js con Prisma
+- Cuando se necesita explorar la estructura real del proyecto antes de proponer cambios
+- Cuando se va a generar código que debe respetar convenciones existentes
+- Cuando se necesita verificar que los cambios no rompieron el build
+
+---
+
+## Fase: sdd-init / sdd-explore
+
+Usar `project_scan` para obtener el mapa completo del proyecto antes de proponer cambios:
+
+```
+project_scan({ force_refresh: true })
+```
+
+Esto devuelve:
+- Rutas del App Router (páginas, layouts, route handlers)
+- Server Actions existentes con sus schemas Zod
+- Modelos de Prisma con campos y relaciones
+- Componentes UI instalados (shadcn) y custom
+
+Con esta información el agente puede identificar seams sin tener que explorar el filesystem manualmente.
+
+---
+
+## Fase: sdd-spec / sdd-design
+
+Usar herramientas granulares para detallar el diseño:
+
+**Entender la capa de datos:**
+```
+project_models({ schema: "base" })
+```
+Devuelve modelos de Prisma con campos, tipos, relaciones y atributos. Usar para saber qué entidades existen y cómo se relacionan.
+
+**Mapear rutas existentes:**
+```
+project_routes({ filter: "all" })
+```
+Devuelve rutas del App Router con: rendering mode (RSC/client), params dinámicos, métodos HTTP (para route handlers), y si tienen loading/error boundaries.
+
+**Ver Server Actions existentes:**
+```
+project_actions({ feature: "users" })
+```
+Devuelve actions con: schema Zod asociado, parámetros, flags de auth y revalidación. Usar como referencia de patrones antes de crear nuevas actions.
+
+---
+
+## Fase: sdd-apply
+
+Usar generadores que respetan las convenciones del proyecto:
+
+**Server Action con Zod + auth + revalidación:**
+```
+generate_action({
+  entity: "user",
+  operation: "create",
+  with_auth: true,
+  prisma_schema: "base"
+})
+```
+Genera código basado en el schema de Prisma real del proyecto, no templates genéricos.
+
+**Página RSC con metadata y estructura correcta:**
+```
+generate_page({
+  path: "/dashboard/users/[id]",
+  type: "detail",
+  with_auth: true,
+  with_metadata: true
+})
+```
+
+**Componente con cn(), tipado explícito y directiva correcta:**
+```
+generate_component({
+  name: "UserCard",
+  feature: "users",
+  type: "display",
+  is_client: false
+})
+```
+
+---
+
+## Fase: sdd-verify
+
+Usar `env_run_check` para validar que los cambios no rompieron nada:
+
+```
+env_run_check({ check: "typecheck" })  → verificar tipos
+env_run_check({ check: "lint" })       → verificar lint
+env_run_check({ check: "test" })       → correr tests
+env_run_check({ check: "build" })      → verificar build completo
+```
+
+También verificar estado de migraciones si hubo cambios en Prisma:
+```
+env_prisma_status()
+```
+
+---
+
+## Fase: sdd-archive
+
+Usar `env_status()` para confirmar que el entorno quedó sano después de los cambios. Los resultados se pueden guardar en Engram como observación de tipo `context`.
+
+---
+
+## Tools disponibles (referencia rápida)
+
+| Tool | Fase SDD | Descripción |
+|------|----------|-------------|
+| `project_scan` | explore | Mapa completo del proyecto |
+| `project_routes` | spec/design | Rutas del App Router |
+| `project_actions` | spec/design | Server Actions con schemas |
+| `project_models` | spec/design | Modelos Prisma con campos |
+| `env_status` | init/archive | Estado del entorno |
+| `env_run_check` | verify | Typecheck, lint, test, build |
+| `env_prisma_status` | verify | Estado de migraciones |
+| `generate_action` | apply | Generar Server Action |
+| `generate_page` | apply | Generar página RSC |
+| `generate_component` | apply | Generar componente React |