arckode-framework 1.3.0 → 1.3.2

package/README.md

@@ -317,13 +317,63 @@ await mail.send({ to: 'user@example.com', subject: 'Bienvenido', html: '<p>Hola<
 ### Storage
 
 ```ts
-import { StorageService } from 'arckode-framework/storage'
-import { LocalAdapter } from 'arckode-framework/storage/local'
+import { StorageService } from 'arckode-framework/modules/storage'
+import { LocalStorageAdapter } from 'arckode-framework/modules/storage/local-adapter'
+
+// En composition-root.ts
+const storage = new StorageService(
+  new LocalStorageAdapter('./uploads', '/uploads')
+)
+
+// Subir un archivo
+const stored = await storage.upload(file, 'avatars')
+// stored.url  → '/uploads/avatars/1234567890-abc.jpg'
+// stored.path → 'avatars/1234567890-abc.jpg'
+```
+
+### File Uploads (multipart/form-data)
+
+El servidor detecta `Content-Type: multipart/form-data` automáticamente y parsea el body
+sin dependencias externas. Los archivos quedan en `req.files`, los campos de texto en `req.body`.
+
+```ts
+import type { UploadedFile } from 'arckode-framework'
+import { ValidationError } from 'arckode-framework'
 
-const storage = new StorageService(new LocalAdapter({ path: './uploads' }))
-const url = await storage.save('avatars/user.png', fileBuffer)
+router.post('/avatar', [auth.authenticate()], async (req) => {
+  const file = req.files?.['avatar']
+  if (!file) throw new ValidationError('Se requiere un archivo')
+
+  const stored = await storageService.upload(file, 'avatars')
+  return { status: 200, body: { url: stored.url } }
+})
 ```
 
+**Desde el cliente:**
+
+```ts
+const form = new FormData()
+form.append('avatar', blob, 'photo.jpg')
+await fetch('/avatar', { method: 'POST', body: form })
+```
+
+**Estructura de `UploadedFile`:**
+
+```ts
+interface UploadedFile {
+  fieldName: string     // nombre del campo en el form
+  originalName: string  // nombre del archivo enviado
+  buffer: Buffer        // contenido binario
+  mimeType: string      // 'image/jpeg', 'application/pdf', etc.
+  size: number          // bytes
+}
+```
+
+> Combiná con `bodyLimit()` para limitar el tamaño máximo:
+> ```ts
+> router.post('/avatar', [bodyLimit(5 * 1024 * 1024)], handler)  // 5MB máx
+> ```
+
 ---
 
 ## Middlewares

package/cli/stubs/claude-md-stub.ts

@@ -67,7 +67,21 @@ src/modules/mi-modulo/
 
 ---
 
-## Protocolo de la IA (4 pasos obligatorios)
+## Protocolo de la IA (5 pasos obligatorios)
+
+### ⚠ CREAR un módulo/vista NUEVA → usar arckode-agent (OBLIGATORIO)
+
+Si el usuario pide crear un módulo, vista o feature nueva:
+1. \`arckode-agent scan\` → lee los módulos existentes (tipos, campos, endpoints)
+2. \`arckode-agent research "<descripción>"\` → investiga el dominio en internet (solo si es nuevo)
+3. Generar código usando scan + research + este CLAUDE.md
+4. \`arckode-agent verify\` → si falla, corregir y repetir (max 10 iteraciones)
+5. Solo decir "listo" cuando verify pasa Y el módulo está en composition-root.ts
+
+**NUNCA generar código sin hacer scan primero.**
+**NUNCA inventar campos que ya existen en otro módulo.**
+
+### MODIFICAR código existente → protocolo manual
 
 \`\`\`
 PASO 1 — IDENTIFICAR ALCANCE
@@ -82,12 +96,8 @@ PASO 2 — VERIFICAR REGLAS
   ¿Comparto una tabla con otro módulo? → NO
   ¿Inyecto ORM al service? → NO (RepositoryAdapter<T> o Repository del dominio)
 
-PASO 3 — GENERAR (estructura nueva)
-  Obligatorios: index.ts, model.ts, types.ts, sockets.ts,
-                service.ts, controller.ts (al root),
-                validators/schema.ts, tests/service.test.ts
-  Opcionales:   repository.ts (si hay queries del dominio repetidas)
-                usecases/ (si hay 3+ flujos DIFERENTES, no CRUD)
+PASO 3 — MODIFICAR (código existente)
+  Respetar estructura existente del módulo
 
 PASO 4 — VERIFICAR
   bun run analyze --json → violations: 0
@@ -169,9 +179,12 @@ Escalar SOLO cuando la condición lo justifica. Si no hay condición → nivel 1
 bun run dev                              # desarrollo con hot reload
 bun run analyze                          # verificar arquitectura + actualiza arckode.json
 bun run analyze:ci                       # modo CI: exit 1 si hay violaciones
-bun arckode make:module Nombre           # generar módulo completo
+bun arckode make:module Nombre           # generar módulo completo (scaffold)
 bun arckode make:connector nombre-x mod1 mod2  # conectar dos módulos (kebab-case)
 bun test                                 # correr todos los tests
+arckode-agent research "descripción"     # investigar dominio ANTES de generar código
+arckode-agent verify                     # verificar typecheck + tests + analyze
+arckode-agent status                     # ver estado del proyecto (módulos, conectores)
 \`\`\`
 
 ---

package/kernel/middlewares.ts

@@ -22,25 +22,30 @@ export function cors(options: {
   const credentials = options.credentials ?? true
 
   return async (req, next): Promise<HttpResponse> => {
+    const requestOrigin = req.headers['origin'] as string | undefined
+
+    // Access-Control-Allow-Origin must be a single value — never a comma-separated list.
+    // When multiple origins are allowed, echo back only the matching request origin.
+    const allowedOrigin = origins.includes('*')
+      ? '*'
+      : requestOrigin && origins.includes(requestOrigin)
+        ? requestOrigin
+        : undefined
+
     if (req.method === 'OPTIONS') {
-      return {
-        status: 204,
-        body: null,
-        headers: {
-          'Access-Control-Allow-Origin': origins.includes('*') ? '*' : origins.join(', '),
-          'Access-Control-Allow-Methods': methods.join(', '),
-          'Access-Control-Allow-Headers': headers.join(', '),
-          'Access-Control-Allow-Credentials': String(credentials),
-          'Access-Control-Max-Age': '86400',
-        },
+      const h: Record<string, string> = {
+        'Access-Control-Allow-Methods': methods.join(', '),
+        'Access-Control-Allow-Headers': headers.join(', '),
+        'Access-Control-Allow-Credentials': String(credentials),
+        'Access-Control-Max-Age': '86400',
       }
+      if (allowedOrigin) h['Access-Control-Allow-Origin'] = allowedOrigin
+      return { status: 204, body: null, headers: h }
     }
 
     const res = await next()
-    const corsHeaders: Record<string, string> = {
-      ...res.headers,
-      'Access-Control-Allow-Origin': origins.includes('*') ? '*' : origins.join(', '),
-    }
+    const corsHeaders: Record<string, string> = { ...res.headers }
+    if (allowedOrigin) corsHeaders['Access-Control-Allow-Origin'] = allowedOrigin
     if (credentials) corsHeaders['Access-Control-Allow-Credentials'] = 'true'
     return { ...res, headers: corsHeaders }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "AI-first TypeScript/Bun framework. Modular, SOLID, zero magic. The AI reads the composition root and knows everything.",
   "type": "module",
   "main": "./kernel/framework.ts",
@@ -17,6 +17,7 @@
     "./adapters/mysql": "./adapters/mysql.ts",
     "./modules/mail": "./modules/mail/index.ts",
     "./modules/storage": "./modules/storage/index.ts",
+    "./modules/storage/local-adapter": "./modules/storage/local-adapter.ts",
     "./modules/queue": "./modules/queue/index.ts",
     "./testing": "./kernel/testing.ts"
   },

package/skills/middlewares/SKILL.md

@@ -57,6 +57,19 @@ router.use(cors({
 
 **Preflight:** el middleware maneja `OPTIONS` automáticamente y retorna 204.
 
+**Múltiples orígenes:** `Access-Control-Allow-Origin` solo acepta UN valor por request
+(no una lista separada por comas — los browsers lo rechazan). El middleware compara el
+header `Origin` del request contra la lista y emite solo el origen que hizo match.
+Si el origin no está en la lista, el header se omite (el browser bloquea el request).
+
+```
+Request:  Origin: https://mi-app.com
+Response: Access-Control-Allow-Origin: https://mi-app.com   ✅
+
+Request:  Origin: https://evil.com
+Response: (sin Access-Control-Allow-Origin)                  → blocked ✅
+```
+
 ---
 
 ## 4. RATE LIMIT