arckode-framework 1.0.0

package/skills/config/SKILL.md

@@ -0,0 +1,253 @@
+# SKILL: Arckode Config — ConfigStore, Logger y Cache
+
+> Activar cuando: configurar variables de entorno, agregar config nueva, usar el logger, trabajar con cache.
+
+---
+
+## 1. CONFIGSTORE + loadEnv
+
+### Setup completo
+
+```ts
+import { ConfigStore, loadEnv } from 'arckode-framework'
+
+// 1. Cargar archivos .env (SIEMPRE await)
+const env = await loadEnv()
+
+// 2. Definir schema y cargar valores
+const config = new ConfigStore()
+config
+  .define({
+    // Servidor
+    PORT:        { type: 'number',  default: 3000 },
+    HOST:        { type: 'string',  default: '0.0.0.0' },
+    NODE_ENV:    { type: 'string',  default: 'development' },
+
+    // Base de datos
+    DB_PATH:     { type: 'string',  default: './data/db.sqlite' },
+    DB_HOST:     { type: 'string',  required: false },
+    DB_PORT:     { type: 'number',  default: 5432 },
+    DB_NAME:     { type: 'string',  required: false },
+    DB_USER:     { type: 'string',  required: false },
+    DB_PASSWORD: { type: 'string',  required: false },
+
+    // Auth
+    JWT_SECRET:  { type: 'string',  required: true },    // fail-fast si falta
+
+    // Opcionales con defaults
+    LOG_LEVEL:   { type: 'string',  default: 'info' },
+    SMTP_HOST:   { type: 'string',  required: false },
+    SMTP_PORT:   { type: 'number',  default: 587 },
+  })
+  .load(env)
+```
+
+### Tipos de config disponibles
+
+| Tipo | Validación | Ejemplo |
+|------|-----------|---------|
+| `string` | Cualquier texto | `'localhost'` |
+| `number` | Parseado de string | `'3000'` → `3000` |
+| `boolean` | `'true'/'false'/'1'/'0'` | `'true'` → `true` |
+| `url` | Válida como URL | `'https://api.com'` |
+| `email` | Válido como email | `'a@b.com'` |
+
+### Opciones por campo
+
+```ts
+config.define({
+  CAMPO: {
+    type:     'string',      // tipo (requerido)
+    required: true,          // fail-fast si no está en .env — default: false
+    default:  'valor',       // valor si no está en .env
+    // required + default no tienen sentido juntos — elegir uno
+  }
+})
+```
+
+### Leer valores
+
+```ts
+config.get('PORT')               // → string (tipo no inferido)
+config.get<number>('PORT')       // → number (con genérico)
+config.get<boolean>('DEBUG')     // → boolean
+config.get('JWT_SECRET')         // → string
+
+// Fail-fast en get(): si la key no fue definida → error en startup
+```
+
+### Archivos .env cargados (en orden de precedencia)
+
+```
+process.env                  ← máxima prioridad (CI/CD, Docker)
+.env.{NODE_ENV}.local        ← ej: .env.development.local
+.env.{NODE_ENV}              ← ej: .env.production
+.env.local                   ← local, no commitear
+.env                         ← base del proyecto
+```
+
+**.gitignore obligatorio:**
+```gitignore
+.env.local
+.env.*.local
+.env.production
+```
+
+---
+
+## 2. LOGGER
+
+### Crear logger
+
+```ts
+import { Logger } from 'arckode-framework'
+
+// En composition-root
+const logger = new Logger('app', 'info')    // nombre, log level
+
+// Logger hijo por módulo (recomendado)
+const log = logger.child('productos')       // → [app.productos]
+const log = logger.child('productos.stock') // → [app.productos.stock]
+```
+
+### Niveles disponibles: `debug` | `info` | `warn` | `error`
+
+```ts
+log.debug('Mensaje de debug', { userId, queryTime })   // solo si LOG_LEVEL=debug
+log.info('Operación completada', { id: item.id })
+log.warn('Comportamiento inesperado', { field, value })
+log.error('Error crítico', { error: err.message, stack: err.stack })
+```
+
+### Qué loguear y cómo
+
+```ts
+// ✅ Info: eventos de negocio con contexto suficiente para debugging
+log.info('Pedido confirmado', { pedidoId, usuarioId, total })
+log.info('Usuario registrado', { userId, email })
+
+// ✅ Warn: comportamiento inusual que no es error
+log.warn('Stock bajo', { productoId, stockActual: 3, umbral: 10 })
+log.warn('Token próximo a expirar', { userId, expiresIn: '5min' })
+
+// ✅ Error: errores reales con contexto completo
+log.error('Fallo al enviar email', { to, error: err.message })
+
+// ❌ Debug en producción — usar solo en desarrollo
+log.debug('Query ejecutada', { sql, params, duration })
+
+// ❌ Nunca loguear datos sensibles
+log.info('Login', { email, password: dto.password })  // NO
+log.info('Login', { email })                           // ✅
+```
+
+### Log level por entorno
+
+```env
+# .env
+LOG_LEVEL=info
+
+# .env.development
+LOG_LEVEL=debug
+```
+
+---
+
+## 3. CACHE
+
+### Setup
+
+```ts
+import { MemoryCache } from 'arckode-framework'
+
+const cache = new MemoryCache()
+
+// Para producción distribuida → Redis
+import { RedisCache } from 'arckode-framework/adapters/redis-cache'
+const cache = new RedisCache({ host: config.get('REDIS_HOST'), port: 6379 })
+```
+
+### API del Cache
+
+```ts
+// Leer
+const value = await cache.get<ProductoDTO[]>('productos:list')  // null si no existe o expiró
+
+// Guardar con TTL (en segundos)
+await cache.set('productos:list', items, 60)     // expira en 60s
+await cache.set('usuario:123', user, 300)        // expira en 5 min
+await cache.set('config:global', data)           // sin TTL — persiste hasta flush()
+
+// Invalidar
+await cache.delete('productos:list')             // borrar una key
+await cache.flush()                              // borrar todo
+
+// Estadísticas
+console.log(cache.stats)
+// { size: 42, hits: 1203, misses: 87, hitRate: '93.27%' }
+```
+
+### Patrón cache-aside (el más común)
+
+```ts
+async listar(): Promise<ProductoDTO[]> {
+  const KEY = 'productos:list'
+
+  const cached = await this.cache.get<ProductoDTO[]>(KEY)
+  if (cached) return cached                              // cache HIT
+
+  const items = await this.repo.findMany({ activo: true })
+  await this.cache.set(KEY, items, 60)                   // guardar 60s
+  return items
+}
+```
+
+### Invalidar al mutar
+
+```ts
+async crear(dto: CreateProductoDTO): Promise<ProductoDTO> {
+  const item = await this.repo.create(...)
+  await this.cache.delete('productos:list')   // invalidar lista
+  return item
+}
+
+async actualizar(id: string, dto: UpdateProductoDTO): Promise<ProductoDTO> {
+  const item = await this.repo.update(id, dto)
+  await this.cache.delete('productos:list')   // invalidar lista
+  await this.cache.delete(`producto:${id}`)  // invalidar el item específico
+  return item!
+}
+```
+
+### Naming convention de keys
+
+```
+{entidad}:list                    → productos:list
+{entidad}:{id}                    → producto:abc-123
+{entidad}:{id}:{sub-recurso}      → usuario:abc-123:pedidos
+{scope}:{entidad}:{filtro}        → admin:reportes:2026-05
+```
+
+### TTL recomendados
+
+| Tipo de dato | TTL |
+|-------------|-----|
+| Listas con paginación | 30-60s |
+| Item individual | 2-5 min |
+| Datos de config | 10-30 min |
+| Contadores/stats | 5 min |
+| Tokens/sessions | igual que el token |
+| Datos de referencia (países, categorías) | 1h+ |
+
+---
+
+## 4. CHECKLIST CONFIG
+
+- [ ] `loadEnv()` con `await` — nunca sincrónico
+- [ ] Keys `required: true` para todo lo que cause crash si falta
+- [ ] Nunca `config.get()` sin haber llamado `config.define()` antes
+- [ ] Logger hijo por módulo: `logger.child('nombre-modulo')`
+- [ ] Nunca loguear passwords, tokens ni datos sensibles
+- [ ] Cache invalidado en toda operación de escritura que afecte la key
+- [ ] TTL explícito en `cache.set()` para datos que cambian frecuentemente
+- [ ] `.env.production` en `.gitignore` — nunca commitear secrets

package/skills/connectors/SKILL.md

@@ -0,0 +1,259 @@
+# SKILL: Arckode Connectors — Puentes entre módulos
+
+> Activar cuando: dos módulos necesitan comunicarse, implementar side effects entre módulos, crear eventos cross-módulo.
+
+---
+
+## 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 actions/service.ts
+import type { PedidosSockets } from '../sockets'
+
+export class PedidosService {
+  private sockets: PedidosSockets = {}
+
+  // Requerido para que el conector pueda inyectar
+  setSockets(sockets: PedidosSockets): void {
+    this.sockets = sockets
+  }
+
+  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:
+
+```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 })
+    },
+  })
+}
+```
+
+---
+
+## 7. EVENTBUS (alternativa para eventos broadcast)
+
+Cuando muchos módulos necesitan reaccionar al mismo evento sin conocerse entre sí:
+
+```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)
+})
+```
+
+**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 actions/service directamente (viola REGLA #1)
+import { PedidosService } from '../modules/pedidos/actions/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
+```
+
+---
+
+## 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()
+})
+```
+
+---
+
+## 10. CHECKLIST CONECTORES
+
+- [ ] Solo importa tipos (no implementaciones) desde `index.ts` de módulos
+- [ ] Sin `if`, `for`, ni lógica de negocio — solo llamadas de delegación
+- [ ] El service emisor implementa `setSockets()` y usa `?.` al llamarlos
+- [ ] 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