arckode-framework 1.0.0

package/skills/helpers/SKILL.md

@@ -0,0 +1,206 @@
+# SKILL: Arckode Helpers y Static — Código compartido y archivos estáticos
+
+> Activar cuando: crear una función utilitaria compartida, servir el frontend compilado, modo monolito, `arckode make:helper`.
+
+---
+
+## 1. HELPERS PUROS (shared/helpers/)
+
+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").
+
+### 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
+
+```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)
+}
+
+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}/actions/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
+
+- [ ] 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

package/skills/middlewares/SKILL.md

@@ -0,0 +1,282 @@
+# SKILL: Arckode Middlewares — Globales y por Ruta
+
+> Activar cuando: agregar CORS, rate limit, timeout, logging, compresión, body limit, auth en rutas, o crear un middleware propio.
+
+---
+
+## 1. IMPORT
+
+```ts
+import {
+  cors,
+  rateLimit,
+  requestLogger,
+  bodyLimit,
+  timeout,
+  compression,
+  requireAuth,
+} from 'arckode-framework/middlewares'
+```
+
+---
+
+## 2. MIDDLEWARES GLOBALES (composition-root.ts)
+
+Los globales se aplican a TODAS las rutas. Registrar en este orden:
+
+```ts
+import { cors, rateLimit, requestLogger, bodyLimit, timeout, compression } from 'arckode-framework/middlewares'
+
+// Orden obligatorio — cada uno depende del anterior
+router.use(timeout(10_000))              // 1. Cortar requests colgados antes que todo
+router.use(cors({ origins: ['https://mi-app.com'], credentials: true }))  // 2. CORS
+router.use(bodyLimit(2 * 1024 * 1024))  // 3. Rechazar bodies > 2MB antes de parsear
+router.use(requestLogger(logger))        // 4. Loguear método, path, status, duración
+router.use(compression())               // 5. Gzip para responses > 1KB (opcional)
+// rate limit: ver sección 3 — puede ser global o por ruta
+```
+
+**El orden importa:** si `timeout` va al final, no puede cortar las fases anteriores.
+
+---
+
+## 3. CORS
+
+```ts
+// Permitir cualquier origen (solo para desarrollo/APIs públicas)
+router.use(cors())
+
+// Origenes específicos (producción)
+router.use(cors({
+  origins:     ['https://mi-app.com', 'https://admin.mi-app.com'],
+  methods:     ['GET', 'POST', 'PUT', 'DELETE'],
+  headers:     ['Content-Type', 'Authorization'],
+  credentials: true,   // necesario si el frontend envía cookies o Authorization
+}))
+```
+
+**Preflight:** el middleware maneja `OPTIONS` automáticamente y retorna 204.
+
+---
+
+## 4. RATE LIMIT
+
+```ts
+// Global: 100 requests por minuto por IP
+const limiter = rateLimit({ windowMs: 60_000, max: 100 })
+router.use(limiter)
+
+// Por ruta específica (más restrictivo para endpoints sensibles)
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60_000,  // 15 minutos
+  max: 5,                  // máximo 5 intentos
+  keyBy: (req) => req.headers['x-forwarded-for'] as string ?? 'anon',
+})
+router.post('/auth/login', [loginLimiter], req => controller.login(req))
+
+// Rate limit por usuario autenticado (después de que auth middleware corra)
+const userLimiter = rateLimit({
+  windowMs: 60_000,
+  max: 200,
+  keyBy: (req) => req.user?.id ?? req.headers['x-forwarded-for'] as string ?? 'anon',
+})
+
+// Resetear límite de un usuario (ej: tras verificación de captcha)
+limiter.reset('192.168.1.1')
+```
+
+**Importante:** El rate limiter usa memoria en proceso — no persiste entre reinicios ni entre múltiples instancias. Para producción distribuida → implementar `RateLimitAdapter` con Redis.
+
+---
+
+## 5. REQUEST LOGGER
+
+```ts
+// Loguea: "POST /auth/login", "POST /auth/login 200 43ms"
+router.use(requestLogger(logger))
+
+// El logger hijo del módulo también puede usarse
+router.use(requestLogger(logger.child('http')))
+```
+
+Output en logs:
+```
+[app.http] POST /auth/login { requestId: 'abc-123' }
+[app.http] POST /auth/login 200 43ms { requestId: 'abc-123', status: 200, duration: 43 }
+```
+
+---
+
+## 6. BODY LIMIT
+
+```ts
+// Default: 1MB
+router.use(bodyLimit())
+
+// Custom: 10MB (para endpoints de upload)
+router.use(bodyLimit(10 * 1024 * 1024))
+
+// Por ruta (más permisivo solo en upload)
+router.post('/archivos/upload', [bodyLimit(50 * 1024 * 1024)], req => controller.upload(req))
+```
+
+Retorna **413** si el body supera el límite.
+
+---
+
+## 7. TIMEOUT
+
+```ts
+// Default: 5 segundos
+router.use(timeout())
+
+// Custom por aplicación
+router.use(timeout(10_000))  // 10s
+
+// Más permisivo para endpoints lentos (reportes, exports)
+router.get('/reportes/export', [timeout(60_000)], req => controller.export(req))
+```
+
+Lanza `InternalError` si el handler no responde en tiempo.
+
+---
+
+## 8. COMPRESSION (gzip)
+
+```ts
+// Comprime responses JSON > 1KB si el cliente acepta gzip
+router.use(compression())
+
+// Custom threshold
+router.use(compression({ threshold: 512 }))  // comprimir si > 512 bytes
+```
+
+**No aplica a:** SSE streams, responses `null`, responses que ya tienen `Content-Encoding`.
+
+---
+
+## 9. MIDDLEWARES POR RUTA
+
+```ts
+// Un middleware
+router.get('/admin', [auth.authenticate('admin')], req => controller.dashboard(req))
+
+// Múltiples middlewares (se ejecutan en orden)
+router.post(
+  '/auth/login',
+  [loginLimiter, bodyLimit(10_000)],
+  req => controller.login(req)
+)
+
+// Auth + role específico
+router.delete(
+  '/usuarios/:id',
+  [auth.authenticate('admin', 'superadmin')],
+  req => controller.eliminar(req)
+)
+```
+
+---
+
+## 10. CREAR UN MIDDLEWARE PROPIO
+
+```ts
+import type { MiddlewareHandler } from 'arckode-framework'
+
+// Middleware que verifica un API key en el header
+export function apiKeyAuth(validKeys: string[]): MiddlewareHandler {
+  return async (req, next) => {
+    const key = req.headers['x-api-key'] as string
+    if (!key || !validKeys.includes(key)) {
+      return { status: 401, body: { error: 'API key inválida' } }
+    }
+    return next()  // siempre llamar next() para continuar la cadena
+  }
+}
+
+// Middleware de auditoría
+export function auditLog(repo: RepositoryAdapter<AuditoriaDTO>): MiddlewareHandler {
+  return async (req, next) => {
+    const res = await next()
+    if (req.method !== 'GET' && res.status < 400) {
+      await repo.create({
+        userId: req.user?.id ?? 'anon',
+        action: `${req.method} ${req.path}`,
+        status: res.status,
+      } as any)
+    }
+    return res
+  }
+}
+
+// Registrar
+router.use(apiKeyAuth(['key-secreta-1', 'key-secreta-2']))
+```
+
+**Regla:** siempre llamar `await next()` y retornar su resultado — excepto cuando querés cortar la cadena (retornar error directo, como en el ejemplo de apiKeyAuth).
+
+---
+
+## 11. CADENA DE EJECUCIÓN
+
+```
+Request entrante
+  → timeout          (global)
+  → cors             (global)
+  → bodyLimit        (global)
+  → requestLogger    (global)
+  → compression      (global)
+  → loginLimiter     (por ruta, si aplica)
+  → auth.authenticate (por ruta, si aplica)
+  → handler          (controller)
+← Response saliente
+```
+
+Los middlewares globales corren ANTES que los de ruta. El error handler del router atrapa excepciones de toda la cadena.
+
+---
+
+## 12. ANTI-PATRONES
+
+```ts
+// ❌ Middleware global que modifica req.body con lógica de negocio
+router.use(async (req, next) => {
+  req.body.precio = req.body.precio * 1.21  // impuesto — NO acá, va en el service
+  return next()
+})
+
+// ❌ Olvidar llamar next() — la request queda colgada
+router.use(async (req, next) => {
+  if (req.headers['x-tenant']) {
+    // ... pero nunca llama next()
+  }
+  // cuelga para requests sin x-tenant
+})
+
+// ❌ Lógica de autenticación duplicada en cada handler
+router.get('/datos', async (req) => {
+  const token = req.headers['authorization']
+  if (!token) return { status: 401, body: { error: '...' } }  // NO
+  // usar auth.authenticate() como middleware por ruta
+})
+
+// ✅ Cortar la cadena cuando es correcto (no llamar next)
+router.use(async (req, next) => {
+  if (req.method === 'OPTIONS') {
+    return { status: 204, body: null }  // cortar la cadena intencionalmente
+  }
+  return next()
+})
+```
+
+---
+
+## 13. CHECKLIST MIDDLEWARES
+
+- [ ] `timeout()` es el PRIMERO en los globales
+- [ ] `cors()` tiene `origins` específicos en producción (no `'*'`)
+- [ ] `bodyLimit()` registrado antes de endpoints que reciben JSON
+- [ ] Rate limiter en endpoints de login/registro (máximo 5/15min)
+- [ ] Middlewares de ruta van en array: `[auth.authenticate('admin')]`
+- [ ] Todo middleware custom llama `await next()` (excepto cuando corta intencionalmente)
+- [ ] No hay lógica de negocio en middlewares — solo cross-cutting concerns