theus-cli 0.2.83 → 0.2.85

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

@@ -1,141 +0,0 @@
----
-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

@@ -1,399 +0,0 @@
----
-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