arckode-framework 1.3.2 → 1.4.1

package/skills/connectors/SKILL.md

@@ -1,316 +1,53 @@
-# SKILL: Arckode Connectors — Puentes entre módulos
+# Conectores — DB, Cache, Storage, etc.
 
-> Activar cuando: dos módulos necesitan comunicarse, implementar side effects entre módulos, crear eventos cross-módulo.
+## Regla cardinal
 
----
-
-## 1. QUÉ ES UN CONECTOR (y cuándo crearlo)
-
-Un conector es el **único canal legal** entre módulos. Se crea cuando:
-- El módulo A necesita reaccionar a algo que hace el módulo B
-- Un evento en B debe disparar una acción en A
-- B necesita datos de A para completar su operación
-
-**NO crear un conector cuando:**
-- Podrías resolver el problema con datos del mismo módulo
-- La comunicación es en un solo sentido sin side effects
-- El módulo B solo necesita mostrar datos del módulo A en una response (usar acción pública directamente en el controller o composition-root)
-
----
-
-## 2. ANATOMÍA DE UN CONECTOR
-
-```ts
-// src/connectors/pedido-inventario.ts
-import type { ConnectorContext } from 'arckode-framework'
-
-// SOLO importar tipos — nunca implementaciones internas de módulos
-import type { PedidosService }    from '../modules/pedidos'     // desde index.ts
-import type { InventarioService } from '../modules/inventario'  // desde index.ts
-
-export function conectarPedidoConInventario(ctx: ConnectorContext): void {
-  // 1. Resolver los módulos que necesitás conectar
-  const pedidos    = ctx.resolveModule<PedidosService>('pedidos')
-  const inventario = ctx.resolveModule<InventarioService>('inventario')
-
-  // 2. Inyectar los sockets — solo delegar, sin lógica
-  pedidos.setSockets({
-    onPedidoConfirmado: async (pedido) => {
-      await inventario.descontarStock(pedido.productoId, pedido.cantidad)
-    },
-    onPedidoCancelado: async (pedido) => {
-      await inventario.reponerStock(pedido.productoId, pedido.cantidad)
-    },
-  })
-}
-```
-
-**Regla de oro:** Si hay un `if` o un `for` en el conector — es lógica de negocio. Moverla al módulo correspondiente.
-
----
-
-## 3. PREPARAR EL SERVICE PARA RECIBIR SOCKETS
-
-El módulo que emite eventos debe implementar `SocketsAware`:
-
-```ts
-// En sockets.ts del módulo pedidos
-export interface PedidosSockets {
-  onPedidoConfirmado?: (pedido: PedidoDTO) => Promise<void>
-  onPedidoCancelado?:  (pedido: PedidoDTO) => Promise<void>
-}
-
-// En service.ts (al root del módulo)
-import type { PedidosSockets } from './sockets'
-
-export class PedidosService {
-  private sockets: PedidosSockets = {}
-
-  // ACUMULA — si dos conectores registran el mismo evento, ambos corren en cadena.
-  // NUNCA usar { ...this.sockets, ...s } — pisa silenciosamente el handler anterior.
-  setSockets(s: Partial<PedidosSockets>): void {
-    const next = s as Record<string, any>
-    const cur = this.sockets as Record<string, any>
-    for (const key of Object.keys(next)) {
-      const h = next[key]
-      if (!h) continue
-      const prev = cur[key]
-      cur[key] = prev ? async (...a: any[]) => { await prev(...a); await h(...a) } : h
-    }
-  }
-
-  async confirmar(id: string): Promise<PedidoDTO> {
-    const pedido = await this.repo.update(id, { estado: 'confirmado' })
-    if (!pedido) throw new NotFoundError('Pedido no encontrado')
-
-    // Disparar el evento — el conector decide qué hacer
-    await this.sockets.onPedidoConfirmado?.(pedido)
-
-    return pedido
-  }
-}
-```
-
-**El `?.` es intencional:** el socket es opcional. Si no hay conector registrado, el módulo funciona igual (solo sin side effects).
-
----
-
-## 4. REGISTRAR EN COMPOSITION-ROOT
-
-```ts
-// src/composition-root.ts
-import { conectarPedidoConInventario } from './connectors/pedido-inventario'
-import { conectarPedidoConNotificaciones } from './connectors/pedido-notificaciones'
-
-// DESPUÉS de registrar los módulos, ANTES de start()
-system.addModule(PedidosModule())
-system.addModule(InventarioModule())
-system.addModule(NotificacionesModule())
-
-// Los conectores van al final — dependen de que los módulos estén inicializados
-system.addConnector('pedido-inventario',      conectarPedidoConInventario)
-system.addConnector('pedido-notificaciones',  conectarPedidoConNotificaciones)
-
-await system.start()
-```
-
-**Orden obligatorio:** módulos → conectores → start.
-
----
-
-## 5. NAMING CONVENTION
-
-```
-src/connectors/
-  {módulo-origen}-{módulo-destino}.ts    → pedido-inventario.ts
-  {evento}-{acción}.ts                   → nuevo-usuario-bienvenida.ts
-```
-
-El nombre del conector en `addConnector()` es solo para logging — puede ser descriptivo:
-```ts
-system.addConnector('pedido→inventario:descontar-stock', conectarPedidoConInventario)
-```
-
----
-
-## 6. CONECTOR CON MÚLTIPLES MÓDULOS
-
-Un conector puede coordinar más de 2 módulos, siempre que solo delegue:
+Los conectores SOLO inyectan dependencia, NO tienen lógica de negocio ni adaptación. Un conector que parsea, transforma, o valida está mal.
 
 ```ts
-export function conectarPedidoCompleto(ctx: ConnectorContext): void {
-  const pedidos        = ctx.resolveModule<PedidosService>('pedidos')
-  const inventario     = ctx.resolveModule<InventarioService>('inventario')
-  const notificaciones = ctx.resolveModule<NotificacionesService>('notificaciones')
-  const auditoria      = ctx.resolveModule<AuditoriaService>('auditoria')
-
-  pedidos.setSockets({
-    onPedidoConfirmado: async (pedido) => {
-      // Cada llamada es una delegación — sin lógica en el medio
-      await inventario.descontarStock(pedido.productoId, pedido.cantidad)
-      await notificaciones.enviarConfirmacion(pedido.usuarioId, pedido.id)
-      await auditoria.registrar('pedido.confirmado', { pedidoId: pedido.id })
-    },
-  })
+// ✅ bien
+class MariaDBConnector {
+  readonly pool: Pool
+  constructor() { this.pool = new Pool({ host: 'localhost' }) }
 }
-```
-
----
-
-## 7. SOCKETS DENTRO VS FUERA DE TRANSACCIÓN
-
-Este es el error más silencioso del patrón sockets. **Hay dos tipos de socket calls:**
-
-### Dentro de `transactor.run()` — SOLO lógica DB crítica
+export const db = new MariaDBConnector()
 
-```ts
-// citas/service.ts
-await this.transactor.run(async () => {
-  cita = await this.repo.create({ ... })
-  await this.sockets.onCitaCreada?.(cita)  // ← SOLO ops DB que deben revertirse si fallan
-})
-```
-
-Reglas:
-- El handler DEBE poder fallar y revertir la transacción completa
-- NO hacer llamadas HTTP (WhatsApp, email) — si el HTTP falla, la transacción falla pero el booking ya ocurrió en la DB
-- Solo poner lógica que tenga sentido dentro de una transacción (ej: reservar un slot)
-
-### Post-commit — notificaciones y side effects
-
-```ts
-// Después del transactor — la cita ya existe, no se puede revertir
-await this.sockets.onCitaCreadaCommitted?.(cita)  // WhatsApp, email, CRM, etc.
-```
-
-Reglas:
-- Si el handler falla, NO revierte la transacción (ya committeó)
-- Ideal para notificaciones, actualizaciones de otros sistemas
-- Puede hacer HTTP, enviar mensajes, actualizar servicios externos
-
-### Convención de nombres
-
-```ts
-// sockets.ts — separar explícitamente por contexto de ejecución
-export interface MiModuloSockets {
-  // Corre DENTRO de transactor.run() — para lógica DB crítica
-  onItemCreado?: (item: ItemDTO) => Promise<void>
-  // Corre DESPUÉS del commit — para notificaciones y side effects
-  onItemCreadoCommitted?: (item: ItemDTO) => Promise<void>
+// ❌ mal — lógica aquí
+class MariaDBConnector {
+  getConnection() { return this.pool }
+  async query(sql) { /* no */ }
 }
 ```
 
-**Regla crítica:** si un socket dispara una llamada HTTP (WhatsApp, email, push notification), DEBE ser un evento `*Committed` post-transacción.
+## Conectores incluidos
 
----
+| Conector | Archivo | Propósito |
+|----------|---------|-----------|
+| `DatabaseConnector` | `/connectors/database.ts` | Pool de conexión DB |
+| `CacheConnector` | `/connectors/cache.ts` | Redis/Memoria |
+| `StorageConnector` | `/connectors/storage.ts` | S3/local |
+| `QueueConnector` | `/connectors/queue.ts` | RabbitMQ/Redis |
 
-## 8. EVENTBUS (alternativa para eventos broadcast)
-
-Cuando muchos módulos necesitan reaccionar al mismo evento sin conocerse entre sí:
+## Error común
 
 ```ts
-// En composition-root.ts
-import { EventBus } from 'arckode-framework/events'
-
-const events = new EventBus()
-
-// Módulo pedidos publica
-pedidos.setSockets({
-  onPedidoConfirmado: async (pedido) => {
-    events.emit('pedido.confirmado', pedido, 'pedidos')
-  },
-})
-
-// Múltiples suscriptores — no se conocen entre sí
-events.on('pedido.confirmado', async (event) => {
-  await inventario.descontarStock(event.data.productoId, event.data.cantidad)
-})
-
-events.on('pedido.confirmado', async (event) => {
-  await notificaciones.enviarConfirmacion(event.data.usuarioId, event.data.id)
-})
+class MySQLConnector { /* ... */ }
+export const mysql = new MySQLConnector() // ← export con nombre concreto
 ```
 
-**Usar EventBus cuando:** múltiples módulos reaccionan al mismo evento y no querés un conector gigante.
-**Usar conectores directos cuando:** la coordinación es entre 2 módulos específicos y el flujo es claro.
-
----
-
-## 8. ANTI-PATRONES DE CONECTORES
-
 ```ts
-// ❌ Importar desde ./service directamente (viola REGLA #1)
-import { PedidosService } from '../modules/pedidos/service'  // NO
-
-// ✅ Solo desde index.ts (puerta pública)
-import type { PedidosService } from '../modules/pedidos'
-
-// ❌ Lógica de negocio en el conector (viola REGLA #3)
-pedidos.setSockets({
-  onPedidoConfirmado: async (pedido) => {
-    if (pedido.total > 1000) {
-      await inventario.priorizar(pedido.productoId)  // decisión de negocio — NO acá
-    } else {
-      await inventario.descontarStock(pedido.productoId, pedido.cantidad)
-    }
-  },
-})
-
-// ✅ Lógica en el módulo, conector solo llama
-pedidos.setSockets({
-  onPedidoConfirmado: async (pedido) => {
-    await inventario.procesarPedido(pedido)  // inventario decide cómo procesar
-  },
-})
-
-// ❌ Conector escribe directamente en tabla de otro módulo (viola REGLA #4)
-pedidos.setSockets({
-  onPedidoConfirmado: async (pedido) => {
-    await orm.update('Inventario', pedido.productoId, { stock: nuevoStock })  // NO
-  },
-})
-
-// ❌ Conector en composition-root antes de módulos
-system.addConnector(...)  // NO
-system.addModule(PedidosModule())  // los módulos deben ir primero
+class DatabaseConnector { /* ... */ }
+export const db = new DatabaseConnector() // ← export genérico (desacoplado)
 ```
 
----
-
-## 9. TESTEAR CONECTORES
-
-Los conectores son difíciles de testear en aislamiento — testear los módulos que emiten/reciben:
-
-```ts
-// Testear que el service llama a los sockets cuando corresponde
-test('confirmar pedido dispara onPedidoConfirmado', async () => {
-  const socketFn = mock(() => Promise.resolve())
-  service.setSockets({ onPedidoConfirmado: socketFn })
-
-  await service.confirmar('pedido-123')
-
-  expect(socketFn).toHaveBeenCalledTimes(1)
-  expect(socketFn).toHaveBeenCalledWith(
-    expect.objectContaining({ estado: 'confirmado' })
-  )
-})
-
-// Testear que funciona SIN sockets (optional chaining)
-test('confirmar pedido funciona sin sockets registrados', async () => {
-  // sin setSockets() — sockets = {}
-  await expect(service.confirmar('pedido-123')).resolves.toBeDefined()
-})
-```
+## Cómo extender
 
----
+Crear archivo en `/connectors/`, export default, registrar en composition-root. Sin lógica de negocio.
 
-## 10. CHECKLIST CONECTORES
+## Troubleshooting
 
-- [ ] Solo importa tipos (no implementaciones) desde `index.ts` de módulos
-- [ ] Sin `if`, `for`, ni lógica de negocio — solo llamadas de delegación
-- [ ] `setSockets()` usa el patrón ACUMULATIVO (for loop + chaining) — NUNCA `{ ...this.sockets, ...s }`
-- [ ] Sockets con HTTP/WhatsApp/email usan eventos `*Committed` — nunca dentro de `transactor.run()`
-- [ ] `setSockets()` usa `?.` al llamar los hooks (son opcionales)
-- [ ] Registrado en composition-root DESPUÉS de los módulos
-- [ ] El módulo funciona correctamente sin el conector (sockets son opcionales)
-- [ ] `arckode analyze` detecta: `CONNECTOR_BUSINESS_LOGIC` si hay lógica
+| Problema | Causa | Fix |
+|----------|-------|-----|
+| Pool timeout | Sin `max` en pool config | `pool: new Pool({ max: 10 })` |
+| Reconexión no automática | Driver no la soporta | Envolver en wrapper que reconecta |
+| Conector con lógica | Parseo/validación dentro | Mover a helper/utils |

package/skills/helpers/SKILL.md

@@ -1,206 +1,37 @@
-# SKILL: Arckode Helpers y Static — Código compartido y archivos estáticos
+# Helpers — Funciones Puras Compartidas
 
-> Activar cuando: crear una función utilitaria compartida, servir el frontend compilado, modo monolito, `arckode make:helper`.
+## Reglas
 
----
+1. Función pura → mismo input = mismo output (sin I/O)
+2. Sin estado, sin side effects
+3. Test solo si lógica compleja (regex, cálculos)
 
-## 1. HELPERS PUROS (shared/helpers/)
+## Built-in
 
-Los helpers son funciones puras — sin estado, sin efectos secundarios, sin imports del framework. Cualquier módulo puede importarlos directamente (la única excepción a "no importar de otros módulos").
+| Helper | Propósito | Ejemplo |
+|--------|-----------|---------|
+| `formatDate` | ISO→legible | `formatDate('2024-01-15')` → `'15 Ene 2024'` |
+| `slugify` | String→URL slug | `slugify('Hola Mundo')` → `'hola-mundo'` |
+| `paginate` | Offset calc | `paginate(page, limit)` → `{ skip, take }` |
+| `maskEmail` | Privacy | `maskEmail('user@test.com')` → `'us***@test.com'` |
+| `sleep` | Async delay | `await sleep(1000)` |
+| `generateId` | UUID | `generateId()` |
+| `deepClone` | Deep copy | `deepClone(obj)` |
 
-### Generar un helper
-
-```bash
-arckode make:helper formato-precio
-# Crea: src/shared/helpers/formato-precio.ts
-```
-
-### Estructura generada
-
-```ts
-// src/shared/helpers/formato-precio.ts
-// Helpers puros — sin estado, sin efectos secundarios, sin dependencias externas
-
-export function formatoPrecioExample(input: string): string {
-  return input.trim()
-}
-```
-
-### Implementar el helper real
+## Helper personalizado
 
 ```ts
-// src/shared/helpers/formato-precio.ts
-export function formatearPrecio(monto: number, moneda = 'DOP'): string {
-  return new Intl.NumberFormat('es-DO', {
-    style: 'currency',
-    currency: moneda,
-  }).format(monto)
+// helpers/string.utils.ts — no helpers/index.ts
+export function truncate(str: string, max: number): string {
+  return str.length > max ? str.slice(0, max) + '...' : str
 }
-
-export function redondear(valor: number, decimales = 2): number {
-  return Math.round(valor * 10 ** decimales) / 10 ** decimales
-}
-```
-
-### Importar desde cualquier módulo
-
-```ts
-// En cualquier service, controller o tipo — import directo permitido
-import { formatearPrecio, redondear } from '../../shared/helpers/formato-precio'
-
-class PedidosService {
-  calcularTotal(items: LineaDTO[]): number {
-    const bruto = items.reduce((sum, i) => sum + i.precio * i.cantidad, 0)
-    return redondear(bruto, 2)
-  }
-}
-```
-
----
-
-## 2. TIPOS DE HELPERS (qué va acá vs dónde)
-
-| Tipo | Dónde va | Ejemplo |
-|------|---------|---------|
-| Función pura de transformación | `shared/helpers/` | `formatearFecha`, `slugify`, `calcularIVA` |
-| Lógica de negocio | `modules/{modulo}/service.ts` | `calcularDescuento(pedido)` |
-| Validación de dominio | `modules/{modulo}/validators/schema.ts` | Schema de validación |
-| Constante compartida | `shared/constants.ts` | `IVA_RATE = 0.18` |
-| Tipo/interfaz compartida | `shared/types.ts` | `Paginado<T>`, `ApiResponse<T>` |
-
-### Señales de que algo NO es un helper
-
-```ts
-// ❌ Tiene efectos secundarios — va en el service
-export async function crearPedidoYNotificar(dto) {
-  const pedido = await orm.create(...)  // NO — helper no puede tocar ORM
-  await mail.send(...)                  // NO — helper no puede usar servicios
-}
-
-// ❌ Depende de estado externo — va en el service
-export function obtenerPrecioActual(productoId: string) {
-  return cache.get(`precio:${productoId}`)  // NO — depende de cache
-}
-
-// ✅ Helper puro — sin dependencias
-export function calcularSubtotal(precio: number, cantidad: number, descuento = 0): number {
-  return precio * cantidad * (1 - descuento)
-}
-```
-
----
-
-## 3. CONSTANTS Y TIPOS COMPARTIDOS
-
-```ts
-// src/shared/constants.ts
-export const IVA_RATE = 0.18
-export const ESTADOS_PEDIDO = ['pendiente', 'confirmado', 'enviado', 'entregado', 'cancelado'] as const
-export type EstadoPedido = typeof ESTADOS_PEDIDO[number]
-
-export const ROLES = ['user', 'admin', 'superadmin'] as const
-export type Rol = typeof ROLES[number]
 ```
 
-```ts
-// src/shared/types.ts
-export interface ApiResponse<T> {
-  data: T
-  message?: string
-}
-
-export interface Paginado<T> {
-  data: T[]
-  total: number
-  page: number
-  limit: number
-  totalPages: number
-}
-
-export interface ErrorResponse {
-  error: string
-  errors?: Record<string, string>
-}
-```
-
----
-
-## 4. STATIC SERVER (modo monolito)
-
-Sirve el frontend compilado desde el mismo servidor Node.js. Para proyectos fullstack donde el backend y frontend corren en el mismo proceso.
-
-### Setup en composition-root.ts
-
-```ts
-import { serveStatic } from 'arckode-framework/static'
-
-// Después de registrar todos los módulos y rutas del API
-// IMPORTANTE: va al final — no interceptar rutas del API
-serveStatic(router, './frontend/dist', {
-  prefix:       '',              // sin prefijo — sirve desde /
-  fallback:     'index.html',   // para SPA (Vue Router, React Router)
-  cacheControl: 'public, max-age=3600',  // 1 hora de cache
-})
-```
-
-### Separar API de archivos estáticos
-
-```ts
-// API bajo /api/* — registrar primero
-router.get('/api/productos', req => ...)
-router.post('/api/auth/login', req => ...)
-
-// Luego los estáticos — captura todo lo demás
-serveStatic(router, './frontend/dist', {
-  prefix:   '',
-  fallback: 'index.html',
-})
-```
-
-### Servir uploads públicos
-
-```ts
-import { serveStatic } from 'arckode-framework/static'
-
-// Archivos subidos por usuarios (no del frontend)
-serveStatic(router, './uploads', {
-  prefix:       '/uploads',
-  cacheControl: 'public, max-age=86400',  // 24h — cambian por nombre único
-})
-```
-
-### MIME types soportados automáticamente
-
-`.html`, `.css`, `.js`, `.json`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.ico`, `.woff`, `.woff2`, `.webp`, `.pdf`
-
----
-
-## 5. ESTRUCTURA RECOMENDADA DEL PROYECTO
-
-```
-src/
-├── composition-root.ts
-├── modules/
-│   ├── productos/
-│   └── pedidos/
-├── connectors/
-│   └── pedido-stock.ts
-└── shared/                       ← código compartido
-    ├── constants.ts              ← constantes de dominio
-    ├── types.ts                  ← tipos/interfaces compartidas
-    └── helpers/
-        ├── formato-precio.ts     ← helpers puros
-        ├── fecha.ts
-        └── slugify.ts
-```
-
----
-
-## 6. CHECKLIST HELPERS
+## Errores silenciosos
 
-- [ ] El helper es una función pura — sin imports de ORM, cache, mail, etc.
-- [ ] Generado con `arckode make:helper nombre` para que quede en `shared/helpers/`
-- [ ] Testeable sin mocks (función pura → test directo)
-- [ ] Constantes compartidas en `shared/constants.ts`, no duplicadas en cada módulo
-- [ ] `serveStatic()` registrado DESPUÉS de todas las rutas de API
-- [ ] `fallback: 'index.html'` para proyectos con SPA routing
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Helper con side effect | Llama API o escribe archivo | Separar en service |
+| Test innecesario | Helper simple (`add(a,b)`) | Confiar en tipo |
+| Export default | Import ambiguo | Export named |
+| Over-engineering | `slugify` en 30 líneas con regex complejo | Usar librería `slug` |