arckode-framework 1.0.0

package/skills/orm/SKILL.md

@@ -0,0 +1,260 @@
+# SKILL: Arckode ORM — Modelos, Queries y Migraciones
+
+> Activar cuando: definir un modelo, escribir queries, crear migración, agregar campo, cambiar schema.
+
+---
+
+## 0. NAMING FIJO (no negociable)
+
+```
+Métodos de service:  list() | getById() | create() | update() | delete()
+Controller actions:  index | show | store | update | destroy
+Tablas DB:           snake_case plural → pedidos, lineas_pedido
+Campos del modelo:   camelCase → usuarioId, fechaEntrega
+```
+
+---
+
+## 1. DEFINIR UN MODELO
+
+```ts
+// En types.ts del módulo
+import type { ModelDefinition } from 'arckode-framework'
+
+export const PedidoModel: ModelDefinition = {
+  table: 'pedidos',
+  fields: {
+    // Tipos: 'string' | 'number' | 'boolean' | 'date' | 'text' | 'json'
+    usuarioId:   { type: 'string',  required: true },
+    productoId:  { type: 'string',  required: true },
+    cantidad:    { type: 'number',  required: true },
+    total:       { type: 'number',  required: true },
+    estado:      { type: 'string',  default: 'pendiente' },
+    notas:       { type: 'text',    required: false },
+    metadata:    { type: 'json',    required: false },
+  },
+  timestamps: true,    // agrega createdAt, updatedAt (RECOMENDADO)
+  softDelete: false,   // true → agrega deletedAt, delete() solo marca, no borra
+}
+```
+
+**Reglas de naming:**
+- Tabla: snake_case plural (`pedidos`, `lineas_pedido`)
+- Campos: camelCase (`usuarioId`, `fechaEntrega`)
+- Solo alfanuméricos y guión bajo — `assertSafeIdentifier()` valida esto en ORM
+- No usar palabras reservadas SQL: `order`, `table`, `select`, `where`
+
+---
+
+## 2. REGISTRAR EL MODELO (composition-root.ts)
+
+```ts
+import { PedidoModel } from './modules/pedidos/types'
+
+// ANTES de llamar system.start()
+orm.define('Pedido', PedidoModel)
+await orm.migrate()    // CREATE TABLE IF NOT EXISTS + drift detection
+```
+
+**Orden importa:** `orm.define()` → `orm.migrate()` → `system.start()`
+
+---
+
+## 3. REPOSITORYADAPTER<T> (la interfaz correcta)
+
+El service recibe `RepositoryAdapter<T>`, nunca `ORM` directo:
+
+```ts
+import type { RepositoryAdapter } from 'arckode-framework'
+import { OrmRepository } from 'arckode-framework'
+
+// En el módulo (index.ts):
+const repo = new OrmRepository<PedidoDTO>(orm, 'Pedido')
+const service = new PedidosService(repo)
+
+// En el service:
+class PedidosService {
+  constructor(private repo: RepositoryAdapter<PedidoDTO>) {}
+}
+```
+
+---
+
+## 4. QUERIES DISPONIBLES
+
+```ts
+// Buscar muchos con filtros
+await repo.findMany(
+  { estado: 'pendiente', usuarioId: userId },  // filtros (AND implícito)
+  { limit: 20, offset: 0, orderBy: 'createdAt', orderDir: 'desc' }
+)
+
+// Buscar por ID
+const pedido = await repo.findById(id)  // null si no existe
+
+// Buscar uno con filtro
+const pedido = await repo.findOne({ usuarioId, estado: 'activo' })
+
+// Crear
+const nuevo = await repo.create({
+  usuarioId: 'u123',
+  productoId: 'p456',
+  cantidad: 2,
+  total: 200,
+})
+
+// Actualizar (solo los campos pasados)
+const actualizado = await repo.update(id, { estado: 'confirmado' })
+
+// Eliminar
+const ok = await repo.delete(id)
+
+// Contar
+const total = await repo.count({ estado: 'pendiente' })
+
+// Paginación
+const resultado = await repo.paginate(
+  { estado: 'pendiente' },
+  { page: 1, limit: 10 }
+)
+// → { data: PedidoDTO[], total: number, page: 1, limit: 10, totalPages: number }
+```
+
+### Filtros disponibles
+Los filtros son **igualdad exacta** (AND implícito). Para queries complejas (LIKE, IN, JOIN) → implementar `RepositoryAdapter<T>` custom con el driver directo.
+
+```ts
+// ✅ Soportado
+{ estado: 'activo', usuarioId: 'u123' }
+
+// ❌ No soportado directamente — necesita adapter custom
+{ total: { gte: 1000 } }
+{ nombre: { like: '%zapato%' } }
+```
+
+---
+
+## 5. TRANSACCIONES
+
+```ts
+// En el service — si necesitás atomicidad entre operaciones
+await orm.transaction(async (tx) => {
+  const txRepo = new OrmRepository<PedidoDTO>(tx, 'Pedido')
+  const txInventarioRepo = new OrmRepository<InventarioDTO>(tx, 'Inventario')
+
+  await txRepo.create(datosPedido)
+  await txInventarioRepo.update(inventarioId, { stock: stockNuevo })
+})
+```
+
+**Importante:** Si el adapter no soporta transacciones (MemoryDb, RecordingDb), el ORM ejecuta sin transacción — no falla, solo no es atómico.
+
+---
+
+## 6. MIGRACIONES MANUALES (SQL explícito)
+
+Para cambios que el auto-migrate no puede hacer (renombrar columna, cambiar tipo, agregar índice):
+
+```ts
+// Generar archivo de migración
+// arckode make:migration add_index_to_pedidos
+
+// src/migrations/1716000000_add_index_to_pedidos.ts
+export async function up(adapter: DbAdapter): Promise<void> {
+  await adapter.run('CREATE INDEX IF NOT EXISTS idx_pedidos_usuario ON pedidos(usuario_id)')
+}
+
+export async function down(adapter: DbAdapter): Promise<void> {
+  await adapter.run('DROP INDEX IF EXISTS idx_pedidos_usuario')
+}
+```
+
+```bash
+arckode db:migrate         # corre up() de migraciones pendientes
+arckode db:migrate --rollback  # corre down() de la última migración
+```
+
+**Tabla de control:** `_arckode_migrations` (no tocar manualmente)
+**Tabla de schema drift:** `_arckode_schema` (usada por `orm.migrate()`, separada)
+
+---
+
+## 7. DRIFT DETECTION (automático)
+
+`orm.migrate()` detecta:
+- **Columnas nuevas en el modelo** → ejecuta `ALTER TABLE ADD COLUMN` automáticamente
+- **Columnas que dejaron de existir en el modelo** → emite WARNING, NO las elimina (datos en producción)
+
+Si necesitás eliminar una columna → hacerlo con una migración manual explícita.
+
+---
+
+## 8. ADAPTERS DE BASE DE DATOS
+
+```ts
+// SQLite (desarrollo)
+import { SqliteAdapter } from 'arckode-framework/adapters/sqlite'
+const db = new SqliteAdapter({ path: './data/db.sqlite' })
+await db.connect()
+
+// MySQL (producción)
+import { MySqlAdapter } from 'arckode-framework/adapters/mysql'
+const db = new MySqlAdapter({
+  host: config.get('DB_HOST'),
+  port: config.get<number>('DB_PORT'),
+  user: config.get('DB_USER'),
+  password: config.get('DB_PASSWORD'),
+  database: config.get('DB_NAME'),
+})
+await db.connect()
+
+// PostgreSQL (producción)
+import { PostgresAdapter } from 'arckode-framework/adapters/postgres'
+const db = new PostgresAdapter({ connectionString: config.get('DATABASE_URL') })
+await db.connect()
+```
+
+**El ORM y todos los services son iguales independientemente del adapter.** Solo cambia el adapter en composition-root.
+
+---
+
+## 9. ANTI-PATRONES DE ORM
+
+```ts
+// ❌ ORM directo en controller
+router.get('/pedidos', async (req) => {
+  return orm.findMany('Pedido')  // NO — viola REGLA #12
+})
+
+// ❌ ORM directo en service (debe ser RepositoryAdapter)
+class PedidosService {
+  constructor(private orm: ORM) {}  // NO — viola REGLA #18
+}
+
+// ❌ N+1: ORM dentro de un loop (viola REGLA #17)
+const pedidos = await repo.findMany()
+for (const p of pedidos) {
+  const user = await orm.findById('Usuario', p.usuarioId)  // N queries
+}
+
+// ❌ Dos módulos escribiendo en la misma tabla (viola REGLA #4)
+// módulo-pedidos: orm.update('Inventario', ...)  → NO
+// módulo-inventario es el dueño de la tabla inventario
+
+// ✅ Para queries complejas: adapter custom o dos queries separadas
+const pedidos = await repo.findMany()
+const userIds = [...new Set(pedidos.map(p => p.usuarioId))]
+// luego pasar userIds al módulo de usuarios por acción pública
+```
+
+---
+
+## 10. CHECKLIST ORM
+
+- [ ] El modelo tiene `table` en snake_case plural
+- [ ] Los campos usan camelCase y tipos válidos
+- [ ] `orm.define()` en composition-root, NO en el módulo
+- [ ] `orm.migrate()` después de todos los `define()`
+- [ ] Service recibe `RepositoryAdapter<T>`, no `ORM`
+- [ ] No hay ORM dentro de loops
+- [ ] Migraciones manuales en `src/migrations/` para cambios de schema complejos

package/skills/realtime/SKILL.md

@@ -0,0 +1,307 @@
+# SKILL: Arckode Realtime — EventBus, Queue y WebSockets
+
+> Activar cuando: comunicación entre módulos broadcast, jobs en background, WebSockets, tiempo real, notificaciones push.
+
+---
+
+## 1. EVENTBUS (pub-sub broadcast)
+
+**Cuándo usar EventBus vs Conectores:**
+- **Conector directo** → 2 módulos específicos, flujo claro y predecible
+- **EventBus** → 1 evento, N módulos reaccionan independientemente entre sí
+
+### Setup en composition-root.ts
+
+```ts
+import { EventBus } from 'arckode-framework/events'
+
+const events = new EventBus()
+
+// Pasar a los módulos que lo necesiten
+const system = new System({ ..., events })
+```
+
+### Emitir eventos (en el service)
+
+```ts
+// El service emite — no sabe quién escucha
+class PedidosService {
+  constructor(private events: EventBus, ...) {}
+
+  async confirmar(id: string): Promise<PedidoDTO> {
+    const pedido = await this.repo.update(id, { estado: 'confirmado' })
+    await this.events.emit('pedido.confirmado', pedido, 'pedidos')
+    return pedido!
+  }
+}
+```
+
+### Suscribirse (en composition-root, no en módulos)
+
+```ts
+// Los suscriptores van en composition-root — no en los módulos
+events.on('pedido.confirmado', async (event) => {
+  const pedido = event.data as PedidoDTO
+  await inventario.descontarStock(pedido.productoId, pedido.cantidad)
+})
+
+events.on('pedido.confirmado', async (event) => {
+  const pedido = event.data as PedidoDTO
+  await notificaciones.enviar(pedido.usuarioId, 'Pedido confirmado')
+})
+
+// Suscribirse una sola vez
+events.once('sistema.iniciado', async (event) => {
+  await seeds.cargar()
+})
+
+// Cancelar suscripción
+const handler = async (event: EventMessage) => { ... }
+events.on('pedido.cancelado', handler)
+events.off('pedido.cancelado', handler)
+```
+
+### Inspeccionar (debug)
+
+```ts
+// Historial de los últimos 100 eventos
+const todos = events.getHistory()
+const soloConfirmados = events.getHistory('pedido.confirmado')
+
+// Cuántos listeners hay por evento
+console.log(events.listeners)  // { 'pedido.confirmado': 2, 'pedido.cancelado': 1 }
+
+// Limpiar historial
+events.clearHistory()
+```
+
+### Nomenclatura de eventos
+
+```
+{módulo}.{acción}            → pedido.confirmado, usuario.registrado
+{módulo}.{entidad}.{acción}  → inventario.stock.agotado
+sistema.{acción}             → sistema.iniciado, sistema.detenido
+```
+
+---
+
+## 2. QUEUE SERVICE (jobs en background)
+
+**Cuándo usar Queue:**
+- Tareas que no deben bloquear la response HTTP (enviar email, generar PDF, procesar imagen)
+- Tareas que pueden fallar y necesitan reintentos automáticos
+- Tareas que deben ejecutarse con delay
+
+### Setup en composition-root.ts
+
+```ts
+import { QueueService, MemoryQueueAdapter } from 'arckode-framework/modules/queue'
+
+const queue = new QueueService(new MemoryQueueAdapter())
+```
+
+### Registrar handlers (antes de dispatch)
+
+```ts
+// Registrar los handlers ANTES de empezar a despachar
+queue.register('enviar-email', async (job) => {
+  const { to, subject, html } = job.data as { to: string; subject: string; html: string }
+  await mail.send({ to: { address: to }, subject, html })
+})
+
+queue.register('generar-reporte', async (job) => {
+  const { userId, periodo } = job.data as { userId: string; periodo: string }
+  const pdf = await generarPDF(userId, periodo)
+  await storage.upload({ ...pdf, fieldName: 'reporte' }, 'reportes')
+})
+
+queue.register('procesar-imagen', async (job) => {
+  const { imagePath, userId } = job.data as { imagePath: string; userId: string }
+  await redimensionarYOptimizar(imagePath)
+})
+```
+
+### Despachar jobs (desde el service)
+
+```ts
+// Fire-and-forget: no espera que el job termine
+async registrar(dto: RegisterDTO): Promise<UserDTO> {
+  const user = await this.repo.create(...)
+
+  // El email no bloquea — se procesa en background
+  await this.queue.dispatch('enviar-email', {
+    to: user.email,
+    subject: 'Bienvenido',
+    html: `<h1>Hola ${user.nombre}!</h1>`,
+  })
+
+  return user
+}
+
+// Con delay (30 segundos)
+await queue.dispatch('recordatorio-carrito', { userId }, { delay: 30_000 })
+
+// Con reintentos personalizados
+await queue.dispatch('procesar-pago', { monto, userId }, { maxAttempts: 5 })
+```
+
+### Manejo de errores y reintentos
+
+```ts
+// MemoryQueueAdapter reintenta automáticamente con backoff exponencial:
+// intento 1 → falla → espera 1s → intento 2 → falla → espera 2s → intento 3
+// maxAttempts default: 3
+
+// El handler recibe el job con metadatos
+queue.register('procesar-pago', async (job) => {
+  console.log(`Intento ${job.attempts}/${job.maxAttempts}`)
+  if (job.error) console.log('Error anterior:', job.error)
+
+  const { monto } = job.data as { monto: number }
+  await procesarPago(monto)
+})
+```
+
+**Nota:** `MemoryQueueAdapter` es solo para desarrollo — los jobs se pierden al reiniciar. Para producción → implementar `QueueAdapter` con Redis o una tabla en BD.
+
+---
+
+## 3. WEBSOCKETS (tiempo real)
+
+### Setup en composition-root.ts
+
+```ts
+import { WSServer } from 'arckode-framework/ws'
+
+const ws = new WSServer()
+
+// Adjuntar al servidor HTTP ANTES de iniciar
+ws.attach(http.server)
+
+await system.start()
+```
+
+### Broadcast a todos los clientes
+
+```ts
+// Desde cualquier service inyectado con ws
+ws.broadcast('pedido.nuevo', {
+  id: pedido.id,
+  total: pedido.total,
+  estado: 'pendiente',
+})
+
+ws.broadcast('stock.actualizado', { productoId, stockActual })
+```
+
+### Enviar a un cliente específico
+
+```ts
+ws.sendTo(clientId, 'notificacion', {
+  tipo: 'success',
+  mensaje: 'Tu pedido fue confirmado',
+})
+```
+
+### Gestionar clientes
+
+```ts
+// Obtener todos los clientes conectados
+const clientes = ws.getClients()
+console.log(`${clientes.length} clientes conectados`)
+```
+
+### Inyectar WebSocket en un módulo
+
+```ts
+// En index.ts del módulo
+create({ logger, orm, router, ws }: ModuleDependencies) {
+  const service = new PedidosService(repo, ws, logger.child('pedidos'))
+  ...
+}
+
+// En actions/service.ts
+class PedidosService {
+  constructor(
+    private repo: RepositoryAdapter<PedidoDTO>,
+    private ws: WSServer,
+    private logger: Logger,
+  ) {}
+
+  async confirmar(id: string): Promise<PedidoDTO> {
+    const pedido = await this.repo.update(id, { estado: 'confirmado' })
+    this.ws.broadcast('pedido.confirmado', { id, estado: 'confirmado' })
+    return pedido!
+  }
+}
+```
+
+### SSE como alternativa (Server-Sent Events)
+
+Para notificaciones unidireccionales servidor → cliente sin WebSocket:
+
+```ts
+// En el controller — SSE es más simple para notificaciones push
+router.get('/eventos', [auth.authenticate()], async (req) => {
+  return {
+    status: 200,
+    stream: async function* () {
+      // Enviar evento inicial
+      yield `data: ${JSON.stringify({ tipo: 'conectado' })}\n\n`
+
+      // Mantener conexión abierta — enviar heartbeat cada 30s
+      while (true) {
+        await new Promise(r => setTimeout(r, 30_000))
+        yield `data: ${JSON.stringify({ tipo: 'heartbeat' })}\n\n`
+      }
+    },
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    },
+  }
+})
+```
+
+---
+
+## 4. COMBINACIONES COMUNES
+
+### EventBus + Queue (decoupled async pipeline)
+
+```ts
+// Módulo emite → EventBus → Queue despacha en background
+events.on('usuario.registrado', async (event) => {
+  const user = event.data as UserDTO
+  await queue.dispatch('enviar-bienvenida', { email: user.email, nombre: user.nombre })
+  await queue.dispatch('configurar-defaults', { userId: user.id })
+})
+```
+
+### Queue + WebSocket (progreso en tiempo real)
+
+```ts
+queue.register('exportar-reporte', async (job) => {
+  const { userId } = job.data as { userId: string }
+
+  ws.sendTo(userId, 'reporte.progreso', { paso: 1, total: 3, mensaje: 'Generando...' })
+  const datos = await obtenerDatos(userId)
+
+  ws.sendTo(userId, 'reporte.progreso', { paso: 2, total: 3, mensaje: 'Formateando...' })
+  const pdf = await generarPDF(datos)
+
+  ws.sendTo(userId, 'reporte.listo', { url: pdf.url })
+})
+```
+
+---
+
+## 5. CHECKLIST REALTIME
+
+- [ ] EventBus: suscriptores en composition-root, NO dentro de módulos
+- [ ] Queue: handlers registrados ANTES del primer dispatch
+- [ ] `MemoryQueueAdapter` solo para dev — jobs se pierden al reiniciar
+- [ ] WebSocket: `ws.attach(http.server)` ANTES de `system.start()`
+- [ ] Eventos nombrados en `{módulo}.{acción}` — no strings aleatorios
+- [ ] Handlers de queue con try/catch si el error debe notificarse al usuario