arckode-framework 1.0.0

package/skills/services/SKILL.md

@@ -0,0 +1,206 @@
+# SKILL: Arckode Services — Mail y Storage
+
+> Activar cuando: enviar emails, subir archivos, gestionar attachments, servir uploads.
+
+---
+
+## 1. MAIL SERVICE
+
+### Setup en composition-root.ts
+
+```ts
+import { MailService } from 'arckode-framework/modules/mail'
+import { SmtpAdapter } from 'arckode-framework/modules/mail/smtp-adapter'
+
+const mail = new MailService(
+  new SmtpAdapter({
+    host:   config.get('SMTP_HOST'),
+    port:   config.get<number>('SMTP_PORT'),
+    user:   config.get('SMTP_USER'),
+    pass:   config.get('SMTP_PASS'),
+    secure: config.get<number>('SMTP_PORT') === 465,
+  }),
+  { address: 'noreply@mi-app.com', name: 'Mi App' },  // from por defecto
+)
+```
+
+**Config requerida en .env:**
+```env
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=mi@gmail.com
+SMTP_PASS=app-password-aqui
+```
+
+---
+
+### API del MailService
+
+```ts
+// Email simple
+await mail.send({
+  to:      { address: 'user@example.com', name: 'Juan' },
+  subject: 'Bienvenido',
+  html:    '<h1>Hola Juan!</h1>',
+  text:    'Hola Juan!',           // fallback plain text (recomendado)
+})
+
+// Múltiples destinatarios
+await mail.send({
+  to:      [{ address: 'a@x.com' }, { address: 'b@x.com' }],
+  cc:      { address: 'cc@x.com' },
+  bcc:     { address: 'bcc@x.com' },
+  subject: 'Notificación',
+  html:    '<p>Mensaje masivo</p>',
+})
+
+// Con adjunto
+await mail.send({
+  to:      { address: 'user@example.com' },
+  subject: 'Tu factura',
+  html:    '<p>Adjunto tu factura</p>',
+  attachments: [{
+    filename:    'factura.pdf',
+    content:     pdfBuffer,           // Buffer
+    contentType: 'application/pdf',
+  }],
+})
+
+// Helpers pre-construidos
+await mail.sendWelcome('user@example.com', 'Juan')
+await mail.sendPasswordReset('user@example.com', resetToken)
+```
+
+---
+
+### Inyectar MailService en un módulo
+
+```ts
+// En index.ts del módulo
+create({ logger, orm, cache, router, auth, mail }: ModuleDependencies) {
+  const service = new AuthService(repo, auth, mail, logger.child('auth'))
+  ...
+}
+
+// En actions/service.ts
+class AuthService {
+  constructor(
+    private repo: RepositoryAdapter<UserDTO>,
+    private auth: Auth,
+    private mail: MailService,
+    private logger: Logger,
+  ) {}
+
+  async registrar(dto: RegisterDTO) {
+    const user = await this.repo.create(...)
+    await this.mail.sendWelcome(user.email, user.nombre)  // no bloquear si falla
+    return user
+  }
+}
+```
+
+**Importante:** Envolver `mail.send()` en try/catch si el email no es crítico — el registro no debería fallar si el correo de bienvenida no llega.
+
+---
+
+### Testear con mock
+
+```ts
+const mockMail = { send: mock(() => Promise.resolve()), sendWelcome: mock(() => Promise.resolve()) }
+const service = new AuthService(repo, auth, mockMail as any, logger)
+
+test('registrar envía email de bienvenida', async () => {
+  await service.registrar({ email: 'a@b.com', password: '12345678', nombre: 'Juan' })
+  expect(mockMail.sendWelcome).toHaveBeenCalledWith('a@b.com', 'Juan')
+})
+```
+
+---
+
+## 2. STORAGE SERVICE
+
+### Setup en composition-root.ts
+
+```ts
+import { StorageService } from 'arckode-framework/modules/storage'
+import { LocalStorageAdapter } from 'arckode-framework/modules/storage/local-adapter'
+
+const storage = new StorageService(
+  new LocalStorageAdapter(
+    './uploads',    // directorio en disco
+    '/uploads',     // URL base pública
+  )
+)
+```
+
+**Para servir los archivos subidos**, agregar el static server:
+```ts
+import { serveStatic } from 'arckode-framework/static'
+serveStatic(router, './uploads', { prefix: '/uploads' })
+```
+
+---
+
+### API del StorageService
+
+```ts
+// Subir archivo
+const stored = await storage.upload(fileUpload, 'avatars')
+// → { url: '/uploads/avatars/1234-abc.png', path: 'avatars/1234-abc.png', ... }
+
+// Eliminar archivo
+await storage.delete('avatars/1234-abc.png')
+
+// Obtener URL pública
+const url = storage.getUrl('avatars/1234-abc.png')
+```
+
+---
+
+### Recibir archivo desde HTTP request
+
+```ts
+// En el controller — el framework parsea multipart/form-data automáticamente
+async uploadAvatar(req: HttpRequest): Promise<HttpResponse> {
+  const file = req.files?.['avatar']  // FileUpload
+  if (!file) throw new ValidationError('Archivo requerido', { avatar: 'requerido' })
+  if (!file.mimeType.startsWith('image/')) {
+    throw new ValidationError('Formato inválido', { avatar: 'debe ser una imagen' })
+  }
+  if (file.size > 5 * 1024 * 1024) {
+    throw new ValidationError('Archivo muy grande', { avatar: 'máximo 5MB' })
+  }
+
+  const stored = await this.service.subirAvatar(req.user!.id, file)
+  return { status: 200, body: { url: stored.url } }
+}
+
+// En el service
+async subirAvatar(userId: string, file: FileUpload): Promise<StoredFile> {
+  const stored = await this.storage.upload(file, `avatars/${userId}`)
+  await this.repo.update(userId, { avatarUrl: stored.url })
+  return stored
+}
+```
+
+---
+
+### Inyectar StorageService en un módulo
+
+```ts
+// ModuleDependencies incluye storage si fue pasado al System
+create({ logger, orm, router, storage }: ModuleDependencies) {
+  const service = new UsuariosService(repo, storage, logger.child('usuarios'))
+  ...
+}
+```
+
+---
+
+### Checklist Mail + Storage
+
+- [ ] `SMTP_*` variables en .env (nunca hardcodeadas)
+- [ ] `mail.send()` con try/catch si el email no es crítico para la operación
+- [ ] Validar `mimeType` y `size` antes de `storage.upload()`
+- [ ] `serveStatic()` configurado si se necesita acceso público a los archivos
+- [ ] Mockear ambos servicios en tests (no enviar emails reales en tests)

package/skills/testing/SKILL.md

@@ -0,0 +1,257 @@
+# SKILL: Arckode Testing — Patrones, Utilidades y Estructura
+
+> Activar cuando: escribir tests, configurar test suite, debuggear tests fallidos, agregar cobertura.
+
+---
+
+## 1. SETUP DEL TEST (sin BD real)
+
+```ts
+import { describe, test, expect, beforeEach, mock } from 'bun:test'
+import { createRecordingOrm, createSilentLogger, createNullCache } from 'arckode-framework/testing'
+import { OrmRepository } from 'arckode-framework'
+import { ProductosService } from '../actions/service'
+import type { ProductoDTO } from '../types'
+
+describe('ProductosService', () => {
+  let service: ProductosService
+
+  beforeEach(() => {
+    const orm  = createRecordingOrm()   // captura SQL sin ejecutar BD
+    const repo = new OrmRepository<ProductoDTO>(orm, 'Producto')
+    service    = new ProductosService(repo, createSilentLogger(), createNullCache())
+  })
+})
+```
+
+**Regla de oro:** Testear el service, no el ORM. El ORM ya tiene sus propios tests.
+
+---
+
+## 2. UTILIDADES DE TESTING
+
+```ts
+import {
+  createRecordingOrm,    // ORM que captura queries sin ejecutar nada
+  createSilentLogger,    // Logger que descarta todo (sin ruido en tests)
+  createNullCache,       // Cache que nunca cachea (siempre miss)
+  createTestClient,      // Cliente HTTP para integration tests
+} from 'arckode-framework/testing'
+
+// RecordingOrm — verificar queries generadas sin BD
+const orm = createRecordingOrm()
+await service.listar()
+const queries = orm.getRecordedQueries()
+expect(queries[0]).toContain('SELECT')
+
+// TestClient — integration tests con router real
+const client = createTestClient(router)
+const res = await client.get('/productos')
+expect(res.status).toBe(200)
+expect(res.body).toBeArray()
+```
+
+---
+
+## 3. ESTRUCTURA MÍNIMA OBLIGATORIA
+
+Cada módulo necesita al menos 2 casos:
+
+```ts
+describe('ProductosService', () => {
+
+  // CASO 1: Happy path
+  test('listar retorna array (vacío si no hay datos)', async () => {
+    const result = await service.listar()
+    expect(Array.isArray(result)).toBe(true)
+  })
+
+  // CASO 2: Error esperado (validación, not found, conflict, etc.)
+  test('crear lanza error si el nombre está vacío', async () => {
+    await expect(service.crear({ nombre: '', precio: 100 }))
+      .rejects.toThrow()
+  })
+
+  // CASO 3 (recomendado): IDOR / autorización
+  test('getById lanza NotFoundError si no existe', async () => {
+    await expect(service.getById('id-inexistente', { id: 'u1', role: 'user' }))
+      .rejects.toThrow('no encontrado')
+  })
+})
+```
+
+**`arckode analyze` detecta:** `TESTS_WITHOUT_CASES` — archivo test sin ningún `test()`.
+
+---
+
+## 4. MOCKEAR DEPENDENCIAS EXTERNAS
+
+```ts
+import { mock } from 'bun:test'
+
+// Mockear el mail service en tests que lo usan
+const mockMail = {
+  send: mock(() => Promise.resolve()),
+}
+
+const service = new AuthService(repo, auth, mockMail as any)
+
+test('registro envía email de bienvenida', async () => {
+  await service.registrar({ email: 'test@test.com', password: '12345678' })
+  expect(mockMail.send).toHaveBeenCalledTimes(1)
+  expect(mockMail.send).toHaveBeenCalledWith(
+    expect.objectContaining({ to: 'test@test.com' })
+  )
+})
+```
+
+---
+
+## 5. INTEGRATION TESTS (router + controller)
+
+```ts
+import { Router } from 'arckode-framework'
+import { createTestClient } from 'arckode-framework/testing'
+
+describe('Productos API', () => {
+  let client: ReturnType<typeof createTestClient>
+
+  beforeEach(() => {
+    const router = new Router()
+    // montar el módulo de prueba
+    const orm    = createRecordingOrm()
+    const repo   = new OrmRepository<ProductoDTO>(orm, 'Producto')
+    const service = new ProductosService(repo, createSilentLogger(), createNullCache())
+    const controller = new ProductosController(service)
+
+    router.get('/productos',     req => controller.index(req))
+    router.post('/productos',    req => controller.store(req))
+    router.delete('/productos/:id', req => controller.destroy(req))
+
+    client = createTestClient(router)
+  })
+
+  test('GET /productos → 200', async () => {
+    const res = await client.get('/productos')
+    expect(res.status).toBe(200)
+    expect(Array.isArray(res.body)).toBe(true)
+  })
+
+  test('POST /productos sin nombre → 400', async () => {
+    const res = await client.post('/productos', { body: { precio: 100 } })
+    expect(res.status).toBe(400)
+    expect(res.body).toHaveProperty('errors')
+  })
+
+  test('POST /productos con datos válidos → 201', async () => {
+    const res = await client.post('/productos', {
+      body: { nombre: 'Zapato', precio: 999 }
+    })
+    expect(res.status).toBe(201)
+    expect(res.body).toHaveProperty('id')
+  })
+})
+```
+
+---
+
+## 6. TESTEAR AUTH (con middleware)
+
+```ts
+import { Auth } from 'arckode-framework'
+import { jwtTokenAdapter } from 'arckode-framework/adapters/jwt'
+
+const auth = new Auth(jwtTokenAdapter, 'test-secret-12345678901234567890', createSilentLogger())
+const token = auth.createToken({ id: 'user-1', role: 'user' })
+const adminToken = auth.createToken({ id: 'admin-1', role: 'admin' })
+
+test('GET /pedidos sin token → 401', async () => {
+  const res = await client.get('/pedidos')
+  expect(res.status).toBe(401)
+})
+
+test('GET /pedidos con token → 200', async () => {
+  const res = await client.get('/pedidos', {
+    headers: { Authorization: `Bearer ${token}` }
+  })
+  expect(res.status).toBe(200)
+})
+
+test('DELETE /admin/algo sin admin → 403', async () => {
+  const res = await client.delete('/admin/algo', {
+    headers: { Authorization: `Bearer ${token}` }  // user, no admin
+  })
+  expect(res.status).toBe(403)
+})
+```
+
+---
+
+## 7. CORRER TESTS
+
+```bash
+# Todos los tests
+bun test
+
+# Tests de un módulo específico
+bun test modules/productos
+
+# Un archivo específico
+bun test modules/productos/tests/service.test.ts
+
+# Con watch (re-corre al cambiar archivos)
+bun test --watch
+
+# Con cobertura
+bun test --coverage
+```
+
+---
+
+## 8. QUÉ NO TESTEAR
+
+- **Los adapters del framework** (SqliteAdapter, jwtTokenAdapter): ya tienen tests propios
+- **El ORM** directamente: testealo via RepositoryAdapter en tu service
+- **El router**: testear el controller con `createTestClient`, no el router directamente
+- **Casos imposibles**: no testear `if` que nunca puede ser `false` con TypeScript strict
+
+---
+
+## 9. ERRORES COMUNES EN TESTS
+
+```ts
+// ❌ Olvidar el await — el test pasa siempre (false positive)
+test('lanza error', () => {
+  expect(service.crear({})).rejects.toThrow()  // sin await → siempre pasa
+})
+
+// ✅ Siempre await en expects async
+test('lanza error', async () => {
+  await expect(service.crear({})).rejects.toThrow()
+})
+
+// ❌ Describir implementación en lugar de comportamiento
+test('llama a repo.create con los datos correctos', ...)
+
+// ✅ Describir el comportamiento observable
+test('crear retorna el producto con id asignado', ...)
+
+// ❌ Test que testea el ORM en lugar del service
+test('ORM recibe query INSERT', async () => {
+  const orm = createRecordingOrm()
+  await service.crear(...)
+  expect(orm.getRecordedQueries()[0]).toContain('INSERT')  // testear el framework, no tu código
+})
+```
+
+---
+
+## 10. CHECKLIST TESTING
+
+- [ ] Mínimo 2 test cases: happy path + error esperado
+- [ ] Usar `createRecordingOrm` (sin BD real en unit tests)
+- [ ] Usar `createSilentLogger` (sin ruido en consola)
+- [ ] Usar `createNullCache` (cache predecible)
+- [ ] Todo `expect(...).rejects` tiene `await`
+- [ ] Los nombres de test describen comportamiento, no implementación
+- [ ] `bun test` pasa sin errores antes del commit