arckode-framework 1.2.2 → 1.3.0

package/cli/stubs/module-stub.ts

@@ -200,8 +200,18 @@ export class ${p.name}Service {
     private readonly cache: CacheAdapter,
   ) {}
 
+  // ACUMULA handlers — nunca pisa el anterior.
+  // Si dos conectores registran el mismo evento, ambos corren en cadena (secuencial).
+  // Para ejecución paralela independiente → usar EventBus en composition-root.ts.
   setSockets(s: Partial<${p.name}Sockets>): void {
-    this.sockets = { ...this.sockets, ...s }
+    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 list(query?: ${p.name}Query): Promise<${p.name}Paginated> {

package/kernel/framework.ts

@@ -1065,6 +1065,14 @@ export class OrmTransactor implements Transactor {
 // 6. ROUTER + HTTP — Enrutamiento con middlewares y error handler
 // ═══════════════════════════════════════════════════════════════
 
+export interface UploadedFile {
+  fieldName: string
+  originalName: string
+  buffer: Buffer
+  mimeType: string
+  size: number
+}
+
 export interface HttpRequest {
   id: string
   method: string
@@ -1073,6 +1081,7 @@ export interface HttpRequest {
   query: Record<string, string>
   headers: Record<string, string>
   body: unknown
+  files?: Record<string, UploadedFile>
   user?: { id: string; role: string }
 }
 
@@ -1318,6 +1327,17 @@ function buildEnvelope(status: number, body: unknown): string {
   return JSON.stringify({ success: true, data: body, meta: null, error: null } satisfies ApiResponse)
 }
 
+function indexOfBuffer(haystack: Buffer, needle: Buffer, offset = 0): number {
+  const limit = haystack.length - needle.length
+  outer: for (let i = offset; i <= limit; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer
+    }
+    return i
+  }
+  return -1
+}
+
 export class NodeServer implements ServerAdapter {
   private server?: ReturnType<typeof createNodeServer>
   private maxBodyBytes: number
@@ -1341,7 +1361,7 @@ export class NodeServer implements ServerAdapter {
 
         await requestStorage.run({ requestId, startTime: Date.now() }, async () => {
           try {
-            const body = await this.readBody(nodeReq, this.maxBodyBytes)
+            const { body, files } = await this.readBody(nodeReq, this.maxBodyBytes)
 
             const url = new URL(nodeReq.url ?? '/', `http://${nodeReq.headers.host ?? 'localhost'}`)
             const query: Record<string, string> = {}
@@ -1355,6 +1375,7 @@ export class NodeServer implements ServerAdapter {
               query,
               headers: nodeReq.headers as Record<string, string>,
               body,
+              ...(files ? { files } : {}),
             }
 
             const res = await handler(req)
@@ -1441,7 +1462,10 @@ export class NodeServer implements ServerAdapter {
     return typeof addr === 'object' && addr ? addr.port : this.port
   }
 
-  private readBody(req: IncomingMessage, maxBytes = 10 * 1024 * 1024): Promise<unknown> {
+  private readBody(
+    req: IncomingMessage,
+    maxBytes = 10 * 1024 * 1024,
+  ): Promise<{ body: unknown; files?: Record<string, UploadedFile> }> {
     return new Promise((resolve, reject) => {
       const chunks: Buffer[] = []
       let total = 0
@@ -1457,14 +1481,90 @@ export class NodeServer implements ServerAdapter {
       })
 
       req.on('end', () => {
-        const raw = Buffer.concat(chunks).toString()
-        if (!raw) return resolve(null)
-        try { resolve(JSON.parse(raw)) } catch { resolve(raw) }
+        const rawBuffer = Buffer.concat(chunks)
+        if (!rawBuffer.length) return resolve({ body: null })
+
+        const contentType = (req.headers['content-type'] ?? '').toLowerCase()
+        const boundaryMatch = contentType.match(/multipart\/form-data;\s*boundary=(.+)/)
+
+        if (boundaryMatch) {
+          const boundary = (boundaryMatch[1] ?? '').trim()
+          const { fields, files } = this.parseMultipart(rawBuffer, boundary)
+          return resolve({ body: fields, files })
+        }
+
+        const raw = rawBuffer.toString()
+        try { resolve({ body: JSON.parse(raw) }) } catch { resolve({ body: raw }) }
       })
 
       req.on('error', reject)
     })
   }
+
+  private parseMultipart(
+    buffer: Buffer,
+    boundary: string,
+  ): { fields: Record<string, string>; files: Record<string, UploadedFile> } {
+    const fields: Record<string, string> = {}
+    const files: Record<string, UploadedFile> = {}
+
+    const firstDelim = Buffer.from(`--${boundary}`)
+    const innerDelim = Buffer.from(`\r\n--${boundary}`)
+    const doubleCRLF = Buffer.from('\r\n\r\n')
+
+    let pos = indexOfBuffer(buffer, firstDelim, 0)
+    if (pos === -1) return { fields, files }
+    pos += firstDelim.length
+
+    while (pos < buffer.length) {
+      // Skip \r\n after boundary line, or detect closing --
+      if (buffer[pos] === 0x2d && buffer[pos + 1] === 0x2d) break
+      if (buffer[pos] === 0x0d && buffer[pos + 1] === 0x0a) pos += 2
+      else break
+
+      const headerEnd = indexOfBuffer(buffer, doubleCRLF, pos)
+      if (headerEnd === -1) break
+
+      const headerStr = buffer.subarray(pos, headerEnd).toString()
+      pos = headerEnd + 4
+
+      const nextBound = indexOfBuffer(buffer, innerDelim, pos)
+      if (nextBound === -1) break
+
+      const partBody = buffer.subarray(pos, nextBound)
+      pos = nextBound + innerDelim.length
+
+      const headers: Record<string, string> = {}
+      for (const line of headerStr.split('\r\n')) {
+        const colon = line.indexOf(':')
+        if (colon === -1) continue
+        headers[line.slice(0, colon).toLowerCase().trim()] = line.slice(colon + 1).trim()
+      }
+
+      const disp = headers['content-disposition'] ?? ''
+      const nameMatch = /name="([^"]*)"/.exec(disp)
+      const fileMatch = /filename="([^"]*)"/.exec(disp)
+      if (!nameMatch) continue
+
+      const fieldName = nameMatch[1] ?? ''
+
+      if (fileMatch) {
+        files[fieldName] = {
+          fieldName,
+          originalName: fileMatch[1] ?? '',
+          buffer: partBody,
+          mimeType: headers['content-type'] ?? 'application/octet-stream',
+          size: partBody.length,
+        }
+      } else {
+        fields[fieldName] = partBody.toString()
+      }
+
+      if (buffer[pos] === 0x2d && buffer[pos + 1] === 0x2d) break
+    }
+
+    return { fields, files }
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -2038,4 +2138,7 @@ export default {
 
   // Response envelope
   // ApiResponse interface is exported as named export above
+
+  // File uploads (multipart/form-data)
+  // UploadedFile interface is exported as named export above
 }

package/modules/storage/index.ts

@@ -1,13 +1,8 @@
 // modules/storage/index.ts — Módulo de almacenamiento
 // Sube y sirve archivos via adapter (local disk, S3, etc.)
 
-export interface FileUpload {
-  fieldName: string
-  originalName: string
-  buffer: Buffer
-  mimeType: string
-  size: number
-}
+import type { UploadedFile as FileUpload } from '../../kernel/framework'
+export type { UploadedFile as FileUpload } from '../../kernel/framework'
 
 export interface StoredFile {
   url: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "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",

package/skills/connectors/SKILL.md

@@ -66,9 +66,17 @@ import type { PedidosSockets } from './sockets'
 export class PedidosService {
   private sockets: PedidosSockets = {}
 
-  // MERGE — no replace. Si dos conectores inyectan sockets, el segundo no pisa al primero.
+  // 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 {
-    this.sockets = { ...this.sockets, ...s }
+    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> {
@@ -149,7 +157,54 @@ export function conectarPedidoCompleto(ctx: ConnectorContext): void {
 
 ---
 
-## 7. EVENTBUS (alternativa para eventos broadcast)
+## 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
+
+```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>
+}
+```
+
+**Regla crítica:** si un socket dispara una llamada HTTP (WhatsApp, email, push notification), DEBE ser un evento `*Committed` post-transacción.
+
+---
+
+## 8. EVENTBUS (alternativa para eventos broadcast)
 
 Cuando muchos módulos necesitan reaccionar al mismo evento sin conocerse entre sí:
 
@@ -253,7 +308,8 @@ test('confirmar pedido funciona sin sockets registrados', async () => {
 
 - [ ] 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()` con MERGE (`{...this.sockets, ...s}`) — no replace
+- [ ] `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)