theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/patrones-postgres/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: patrones-postgres
+description: Patrones de base de datos PostgreSQL para optimización de consultas, diseño de esquemas, indexación y seguridad.
+---
+
+# Patrones de PostgreSQL
+
+Referencia rápida de buenas prácticas de PostgreSQL. Para orientación detallada, usa el agente `revisor-bd`.
+
+## Cuándo activarla
+
+- Escribir consultas SQL o migraciones
+- Diseñar esquemas de base de datos
+- Diagnosticar consultas lentas
+- Implementar Row Level Security
+- Configurar pooling de conexiones
+
+## Referencia rápida
+
+### Chuleta de índices
+
+| Patrón de consulta | Tipo de índice | Ejemplo |
+|--------------|------------|---------|
+| `WHERE col = value` | B-tree (por defecto) | `CREATE INDEX idx ON t (col)` |
+| `WHERE col > value` | B-tree | `CREATE INDEX idx ON t (col)` |
+| `WHERE a = x AND b > y` | Compuesto | `CREATE INDEX idx ON t (a, b)` |
+| `WHERE jsonb @> '{}'` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| `WHERE tsv @@ query` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| Rangos de series temporales | BRIN | `CREATE INDEX idx ON t USING brin (col)` |
+
+### Referencia rápida de tipos de datos
+
+| Caso de uso | Tipo correcto | Evita |
+|----------|-------------|-------|
+| IDs | `bigint` | `int`, UUID aleatorio |
+| Cadenas | `text` | `varchar(255)` |
+| Timestamps | `timestamptz` | `timestamp` |
+| Dinero | `numeric(10,2)` | `float` |
+| Flags | `boolean` | `varchar`, `int` |
+
+### Patrones comunes
+
+**Orden en índices compuestos:**
+```sql
+-- Primero las columnas de igualdad, luego las de rango
+CREATE INDEX idx ON orders (status, created_at);
+-- Sirve para: WHERE status = 'pending' AND created_at > '2024-01-01'
+```
+
+**Índice de cobertura (covering):**
+```sql
+CREATE INDEX idx ON users (email) INCLUDE (name, created_at);
+-- Evita la lectura de la tabla para SELECT email, name, created_at
+```
+
+**Índice parcial:**
+```sql
+CREATE INDEX idx ON users (email) WHERE deleted_at IS NULL;
+-- Índice más pequeño, solo incluye usuarios activos
+```
+
+**Política RLS (optimizada):**
+```sql
+CREATE POLICY policy ON orders
+  USING ((SELECT auth.uid()) = user_id);  -- ¡Envuélvelo en SELECT!
+```
+
+**UPSERT:**
+```sql
+INSERT INTO settings (user_id, key, value)
+VALUES (123, 'theme', 'dark')
+ON CONFLICT (user_id, key)
+DO UPDATE SET value = EXCLUDED.value;
+```
+
+**Paginación por cursor:**
+```sql
+SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
+-- O(1) frente a OFFSET, que es O(n)
+```
+
+**Procesamiento de colas:**
+```sql
+UPDATE jobs SET status = 'processing'
+WHERE id = (
+  SELECT id FROM jobs WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED
+) RETURNING *;
+```
+
+### Detección de antipatrones
+
+```sql
+-- Encontrar claves foráneas sin índice
+SELECT conrelid::regclass, a.attname
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND a.attnum = ANY(i.indkey)
+  );
+
+-- Encontrar consultas lentas
+SELECT query, mean_exec_time, calls
+FROM pg_stat_statements
+WHERE mean_exec_time > 100
+ORDER BY mean_exec_time DESC;
+
+-- Comprobar el bloat de las tablas
+SELECT relname, n_dead_tup, last_vacuum
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;
+```
+
+### Plantilla de configuración
+
+```sql
+-- Límites de conexiones (ajustar según la RAM)
+ALTER SYSTEM SET max_connections = 100;
+ALTER SYSTEM SET work_mem = '8MB';
+
+-- Timeouts
+ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
+ALTER SYSTEM SET statement_timeout = '30s';
+
+-- Monitoreo
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Valores de seguridad por defecto
+REVOKE ALL ON SCHEMA public FROM public;
+
+SELECT pg_reload_conf();
+```
+
+## Relacionado
+
+- Agente: `revisor-bd` — flujo completo de revisión de bases de datos
+- Skill: `patrones-backend` — patrones de API y de backend

package/vendor/theus-arsenal/skills/patrones-prisma/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: patrones-prisma
+description: Patrones de Prisma ORM para backends TypeScript — diseño de schema, optimización de queries, transacciones, paginación y trampas críticas como updateMany devolviendo count en vez de registros, timeouts de $transaction, migrate dev reseteando la BD, @updatedAt omitido en escrituras masivas y agotamiento de conexiones en serverless.
+version: "1.0.0"
+---
+
+# Patrones de Prisma
+
+Patrones de producción y trampas no obvias de Prisma ORM en backends TypeScript.
+
+> **Verifica tu versión antes de aplicar los patrones.** La superficie de API de Prisma ha evolucionado entre versiones mayores:
+>
+> ```bash
+> npx prisma --version
+> ```
+>
+> Diferencias notables de API entre versiones:
+> - `relationJoins` puede cargar relaciones vía JOIN en lugar de queries separadas, pero puede causar explosión de filas en relaciones 1:N grandes o `include` profundos — haz benchmark de ambos enfoques
+> - Se añadieron el modificador de campo `omit` y la API de Client Extensions `prisma.$extends`
+> - **Instalaciones más recientes**: el paquete puede llamarse `prisma` en vez de `@prisma/client`; `PrismaClient` puede requerir un driver adapter (p. ej. `@prisma/adapter-pg`); `datasource.url` puede vivir en `prisma.config.ts` en lugar de `schema.prisma`
+> - Los comandos del CLI (`migrate dev`, `migrate deploy`, `generate`) no han cambiado entre versiones
+
+## Cuándo activar
+
+- Al diseñar o modificar modelos y relaciones del schema de Prisma
+- Al escribir queries, transacciones o lógica de paginación
+- Al usar `updateMany`, `deleteMany` o cualquier operación masiva
+- Al ejecutar o planificar migraciones de base de datos
+- Al desplegar en entornos serverless (Vercel, Lambda, Cloudflare Workers)
+- Al implementar soft delete o filtrado de filas multi-tenant
+
+## Conceptos centrales
+
+### Estrategia de IDs
+
+| Estrategia | Úsala cuando | Evítala cuando |
+|---|---|---|
+| `@default(cuid())` | Opción por defecto — segura en URLs, ordenable, sin colisiones | Se necesitan IDs secuenciales para sistemas externos |
+| `@default(uuid())` | Se requiere interoperabilidad con sistemas no-Prisma | Tablas con alta escritura (los UUID aleatorios fragmentan los índices B-tree) |
+| `@default(autoincrement())` | Tablas de unión internas, logs de auditoría | IDs expuestos al público (revela el conteo de registros) |
+
+### Defaults del schema
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  email     String    @unique  // @unique ya crea un índice — no hace falta @@index
+  name      String
+  role      Role      @default(USER)
+  posts     Post[]
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+  deletedAt DateTime?
+
+  @@index([createdAt])
+  @@index([deletedAt, createdAt]) // compuesto para queries de soft-delete + ordenamiento
+}
+```
+
+- Añade `@@index` en cada foreign key y en cada columna usada en `WHERE` u `ORDER BY`.
+- Declara `deletedAt DateTime?` desde el inicio cuando el soft delete sea un requisito previsible — añadirlo después exige una migración sobre una tabla viva.
+- Prisma establece `updatedAt @updatedAt` automáticamente solo en `update` y `upsert` (ver la trampa de actualizaciones masivas en Anti-patrones).
+
+### `include` vs `select`
+
+| | `include` | `select` |
+|---|---|---|
+| Devuelve | Todos los campos escalares + las relaciones indicadas | Solo los campos indicados |
+| Úsalo cuando | Necesitas la mayoría de campos más una relación | Rutas calientes, tablas grandes, evitar sobre-lectura |
+| Rendimiento | Puede sobre-leer en tablas anchas | Payload mínimo, más rápido en datasets grandes |
+| Nota Prisma 5 | Usa JOIN por defecto (`relationJoins`) | Igual |
+
+```ts
+// include — todas las columnas + relación
+const user = await prisma.user.findUnique({
+  where: { id },
+  include: { posts: { select: { id: true, title: true } } },
+});
+
+// select — allowlist explícita
+const user = await prisma.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true },
+});
+```
+
+Nunca devuelvas entidades crudas de Prisma en respuestas de API — mapea a DTOs de respuesta para controlar los campos expuestos:
+
+```ts
+// MAL: filtra passwordHash, deletedAt y campos internos
+return await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// BIEN: mapeo explícito a DTO
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+return { id: user.id, name: user.name, email: user.email };
+```
+
+### Selección de la forma de transacción
+
+| Situación | Usa |
+|---|---|
+| Operaciones independientes, sin interdependencia | Forma de array |
+| Un paso posterior depende de un resultado anterior | Forma interactiva |
+| Hay llamadas externas (email, HTTP) involucradas | Fuera de la transacción por completo |
+
+```ts
+// Forma de array — agrupada en un solo round trip
+const [user, post] = await prisma.$transaction([
+  prisma.user.update({ where: { id }, data: { name } }),
+  prisma.post.create({ data: { title, authorId: id } }),
+]);
+
+// Forma interactiva — usa solo el cliente tx, nunca el cliente prisma externo
+const post = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  if (user.role !== 'ADMIN') throw new Error('Forbidden');
+  return tx.post.create({ data: { title, authorId: user.id } });
+});
+```
+
+### Singleton de PrismaClient
+
+Cada instancia de `PrismaClient` abre su propio pool de conexiones. Instancia una sola vez.
+
+```ts
+// lib/prisma.ts
+
+// Opción A — inicialización con adapter (requerida por instalaciones recientes de Prisma)
+import { PrismaClient } from '@prisma/client'; // o la ruta del cliente generado en tu setup
+import { PrismaPg } from '@prisma/adapter-pg';
+
+function createPrismaClient() {
+  const adapter = new PrismaPg({
+    connectionString: process.env.DATABASE_URL!,
+  });
+  return new PrismaClient({
+    adapter,
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
+  });
+}
+
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+
+export const prisma = globalForPrisma.prisma ?? createPrismaClient();
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+
+// Opción B — inicialización directa (instalaciones antiguas, sin adapter)
+// import { PrismaClient } from '@prisma/client';
+// export const prisma = globalForPrisma.prisma ?? new PrismaClient({ ... });
+```
+
+Usa la Opción A si tu instalación de Prisma requiere el argumento `adapter` en el constructor de `PrismaClient`.
+Usa la Opción B si `new PrismaClient()` funciona sin argumentos. Deja que el compilador te diga cuál es la correcta.
+
+El patrón `globalThis` evita instancias duplicadas durante el hot reload (Next.js, nodemon, ts-node-dev).
+
+### El problema N+1
+
+Cargar relaciones dentro de un bucle emite una query por fila.
+
+```ts
+// MAL: N+1 — una query extra por usuario
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// BIEN: una sola query
+const users = await prisma.user.findMany({ include: { posts: true } });
+```
+
+Con `relationJoins` de Prisma 5+, la forma con `include` usa un solo JOIN. En conjuntos 1:N grandes esto puede aumentar el tamaño del resultado — haz benchmark de ambos enfoques si la relación puede devolver muchas filas por padre.
+
+## Ejemplos de código
+
+### Paginación por cursor (preferida para feeds y datasets grandes)
+
+```ts
+async function getPosts(cursor?: string, limit = 20) {
+  const items = await prisma.post.findMany({
+    where: { published: true },
+    orderBy: [
+      { createdAt: 'desc' },
+      { id: 'desc' }, // orden secundario: evita paginación inestable con timestamps duplicados
+    ],
+    take: limit + 1,
+    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
+  });
+
+  const hasNextPage = items.length > limit;
+  if (hasNextPage) items.pop();
+
+  return { items, nextCursor: hasNextPage ? items[items.length - 1].id : null };
+}
+```
+
+Pide `limit + 1` y haz pop — la forma canónica de detectar `hasNextPage` sin una query de conteo extra. Incluye siempre un campo único (p. ej. `id`) como `orderBy` secundario para evitar paginación inestable cuando varias filas comparten el mismo timestamp. Usa paginación por offset solo cuando los usuarios necesiten saltar a páginas arbitrarias (tablas de administración).
+
+### Soft delete
+
+```ts
+// Filtra siempre de forma explícita — no dependas de middleware (oculta el comportamiento, difícil de depurar)
+const activeUsers = await prisma.user.findMany({ where: { deletedAt: null } });
+
+await prisma.user.update({ where: { id }, data: { deletedAt: new Date() } });
+await prisma.user.update({ where: { id }, data: { deletedAt: null } }); // restaurar
+```
+
+### Manejo de errores
+
+```ts
+import { Prisma } from '@prisma/client'; // o la ruta del cliente generado en tu setup
+
+try {
+  await prisma.user.create({ data: { email } });
+} catch (e) {
+  if (e instanceof Prisma.PrismaClientKnownRequestError) {
+    if (e.code === 'P2002') throw new ConflictError('El email ya existe');
+    if (e.code === 'P2025') throw new NotFoundError('Registro no encontrado');
+    if (e.code === 'P2003') throw new BadRequestError('El registro referenciado no existe');
+  }
+  throw e;
+}
+```
+
+Códigos comunes: `P2002` violación de unicidad · `P2025` no encontrado · `P2003` violación de foreign key.
+
+Captura en el límite del servicio y traduce a errores de dominio. Nunca expongas mensajes crudos de Prisma a los consumidores de la API.
+
+### Pool de conexiones — serverless
+
+Incrusta los parámetros de conexión directamente en `DATABASE_URL` — la concatenación de strings se rompe si la URL ya tiene parámetros de query (p. ej. `?schema=public`):
+
+```bash
+# .env — preferido: parámetros incrustados en la URL
+DATABASE_URL="postgresql://user:pass@host/db?connection_limit=1&pool_timeout=20"
+
+# Con un pooler externo (PgBouncer, pooler de Supabase)
+DATABASE_URL="postgresql://user:pass@host/db?pgbouncer=true&connection_limit=1"
+```
+
+```ts
+// Vercel, AWS Lambda y runtimes serverless similares:
+// limita el pool a 1 por instancia; connection_limit y pool_timeout se controlan vía DATABASE_URL
+
+// Setup con adapter (si tu instalación de Prisma requiere adapter):
+import { PrismaClient } from '@prisma/client';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+const prisma = new PrismaClient({
+  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+});
+
+// Setup directo (si tu instalación de Prisma no requiere adapter):
+// const prisma = new PrismaClient();
+```
+
+## Anti-patrones
+
+### `updateMany` devuelve un count, no registros
+
+```ts
+// MAL: el resultado es { count: 2 } — users[0] es undefined
+const users = await prisma.user.updateMany({ where: { role: 'GUEST' }, data: { role: 'USER' } });
+
+// BIEN: captura los IDs primero, luego actualiza, luego lee solo las filas afectadas
+const targets = await prisma.user.findMany({
+  where: { role: 'GUEST' },
+  select: { id: true },
+});
+const ids = targets.map((u) => u.id);
+await prisma.user.updateMany({ where: { id: { in: ids } }, data: { role: 'USER' } });
+const updated = await prisma.user.findMany({ where: { id: { in: ids } } });
+```
+
+Lo mismo aplica a `deleteMany` — devuelve `{ count: n }`, nunca las filas eliminadas.
+
+### La forma interactiva de `$transaction` expira a los 5 segundos
+
+```ts
+// MAL: una llamada externa dentro de la transacción excede los 5 s por defecto → "Transaction already closed"
+await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  await sendWelcomeEmail(user.email); // llamada externa
+  await tx.user.update({ where: { id }, data: { emailSent: true } });
+});
+
+// BIEN: las llamadas externas fuera de la transacción
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+await sendWelcomeEmail(user.email);
+await prisma.user.update({ where: { id }, data: { emailSent: true } });
+
+// Sube el timeout solo cuando el procesamiento masivo lo necesite de verdad
+await prisma.$transaction(async (tx) => { ... }, { timeout: 30_000 });
+```
+
+### `migrate dev` puede resetear la base de datos
+
+`migrate dev` detecta drift del schema y puede pedir resetear la BD, eliminando todos los datos.
+
+```bash
+# NUNCA en dev compartido, staging o producción
+npx prisma migrate dev --name add_column
+
+# Seguro en todas partes salvo dev local individual
+npx prisma migrate deploy
+
+# Verificar drift sin aplicar
+npx prisma migrate diff \
+  --from-migrations ./prisma/migrations \
+  --to-schema-datamodel ./prisma/schema.prisma \
+  --shadow-database-url "$SHADOW_DATABASE_URL"
+```
+
+### Editar manualmente un archivo de migración rompe deploys futuros
+
+Prisma calcula el checksum de cada archivo de migración. Editarlo después de aplicarlo causa `P3006 checksum mismatch` en cada entorno donde el original ya corrió. Crea una migración nueva en su lugar.
+
+### Los cambios rupturistas de schema requieren migración en varios pasos
+
+Añadir `NOT NULL` a una columna existente o renombrar una columna en una sola migración bloqueará la tabla o perderá datos. Usa expand-and-contract:
+
+```bash
+# Paso 1: crea la migración en local, luego despliega
+npx prisma migrate dev --name add_new_column   # solo local
+npx prisma migrate deploy                       # staging / producción
+```
+
+```ts
+// Paso 2: backfill de datos (en un script o job de migración, no en la shell)
+await prisma.user.updateMany({ data: { newColumn: derivedValue } });
+```
+
+```bash
+# Paso 3: crea la migración de la restricción NOT NULL en local, luego despliega
+npx prisma migrate dev --name make_new_column_required  # solo local
+npx prisma migrate deploy                               # staging / producción
+```
+
+### `@updatedAt` no se dispara en `updateMany`
+
+`@updatedAt` se establece automáticamente solo en `update` y `upsert`. Las escrituras masivas lo dejan desactualizado.
+
+```ts
+// MAL: updatedAt se queda con su valor viejo
+await prisma.post.updateMany({ where: { authorId }, data: { published: true } });
+
+// BIEN
+await prisma.post.updateMany({
+  where: { authorId },
+  data: { published: true, updatedAt: new Date() },
+});
+```
+
+### Soft delete + `findUniqueOrThrow` filtra registros eliminados
+
+`findUniqueOrThrow` lanza `P2025` solo cuando la fila no existe en la BD. Las filas soft-deleted siguen existiendo y se devuelven sin error.
+
+`findUniqueOrThrow` exige un campo con restricción única en `where` — añadir `deletedAt: null` junto a `id` rompe el tipo porque `{ id, deletedAt }` no es una restricción única compuesta. Usa `findFirstOrThrow` en su lugar.
+
+```ts
+// MAL: devuelve al usuario soft-deleted
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// MAL: error de tipos de Prisma — { id, deletedAt } no es una restricción única
+const user = await prisma.user.findUniqueOrThrow({ where: { id, deletedAt: null } });
+
+// BIEN: findFirstOrThrow admite condiciones where arbitrarias
+const user = await prisma.user.findFirstOrThrow({ where: { id, deletedAt: null } });
+```
+
+### `deleteMany` sin `where` elimina todas las filas
+
+```ts
+// MAL: vacía la tabla silenciosamente
+await prisma.post.deleteMany();
+
+// BIEN
+await prisma.post.deleteMany({ where: { authorId: userId } });
+```
+
+## Buenas prácticas
+
+| Regla | Razón |
+|---|---|
+| `migrate deploy` en CI/CD, `migrate dev` solo en local | `migrate dev` puede resetear la BD ante drift |
+| Mapea entidades a DTOs de respuesta | Evita filtrar campos internos |
+| Captura `PrismaClientKnownRequestError` en el límite del servicio | Traduce a errores de dominio |
+| Prefiere los métodos `*OrThrow` sobre chequeos manuales de null | Lanza P2025 automáticamente; usa `findFirstOrThrow` al filtrar por campos no únicos |
+| `connection_limit=1` + pooler externo en serverless | Evita el agotamiento de conexiones |
+| Proporciona siempre `where` en `deleteMany` | Evita vaciar la tabla por accidente |
+| Establece `updatedAt: new Date()` manualmente en `updateMany` | `@updatedAt` omite las escrituras masivas |
+
+## Skills relacionadas
+
+- `patrones-postgres` — indexación y tuning de conexiones a nivel PostgreSQL
+- `migraciones-bd` — planificación de migraciones en varios pasos para producción
+- `patrones-backend` — diseño general de API y capa de servicios