arckode-framework 1.0.0

package/modules/queue/index.ts

@@ -0,0 +1,78 @@
+// modules/queue/index.ts — Módulo de colas / jobs
+// Procesa tareas en background. Adapter intercambiable (in-process, Redis, DB).
+
+export interface Job {
+  id: string
+  name: string
+  data: unknown
+  attempts: number
+  maxAttempts: number
+  createdAt: string
+  error?: string
+}
+
+export type JobHandler = (job: Job) => Promise<void>
+
+export interface QueueAdapter {
+  push(name: string, data: unknown, opts?: { delay?: number; maxAttempts?: number }): Promise<string>
+  process(name: string, handler: JobHandler): void
+  onFailed?(name: string, job: Job, error: Error): void
+}
+
+export class QueueService {
+  private handlers = new Map<string, JobHandler>()
+
+  constructor(private adapter: QueueAdapter) {}
+
+  async dispatch(name: string, data: unknown, opts?: { delay?: number; maxAttempts?: number }): Promise<string> {
+    return this.adapter.push(name, data, opts)
+  }
+
+  register(name: string, handler: JobHandler): void {
+    this.handlers.set(name, handler)
+    this.adapter.process(name, handler)
+  }
+}
+
+// ─── Adapter en memoria (para desarrollo) ───
+export class MemoryQueueAdapter implements QueueAdapter {
+  private handlers = new Map<string, JobHandler>()
+  private jobs: Job[] = []
+
+  async push(name: string, data: unknown, opts?: { delay?: number; maxAttempts?: number }): Promise<string> {
+    const job: Job = {
+      id: crypto.randomUUID(),
+      name,
+      data,
+      attempts: 0,
+      maxAttempts: opts?.maxAttempts ?? 3,
+      createdAt: new Date().toISOString(),
+    }
+
+    const execute = async () => {
+      const handler = this.handlers.get(name)
+      if (!handler) return
+      try {
+        job.attempts++
+        await handler(job)
+      } catch (error) {
+        job.error = String(error)
+        if (job.attempts < job.maxAttempts) {
+          setTimeout(execute, 1000 * job.attempts)
+        }
+      }
+    }
+
+    if (opts?.delay) {
+      setTimeout(execute, opts.delay)
+    } else {
+      process.nextTick(execute)
+    }
+
+    return job.id
+  }
+
+  process(name: string, handler: JobHandler): void {
+    this.handlers.set(name, handler)
+  }
+}

package/modules/storage/index.ts

@@ -0,0 +1,40 @@
+// 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
+}
+
+export interface StoredFile {
+  url: string
+  path: string
+  originalName: string
+  mimeType: string
+  size: number
+}
+
+export interface StorageAdapter {
+  upload(file: FileUpload, directory?: string): Promise<StoredFile>
+  delete(path: string): Promise<void>
+  getUrl(path: string): string
+}
+
+export class StorageService {
+  constructor(private adapter: StorageAdapter) {}
+
+  async upload(file: FileUpload, directory?: string): Promise<StoredFile> {
+    return this.adapter.upload(file, directory)
+  }
+
+  async delete(path: string): Promise<void> {
+    return this.adapter.delete(path)
+  }
+
+  getUrl(path: string): string {
+    return this.adapter.getUrl(path)
+  }
+}

package/modules/storage/local-adapter.ts

@@ -0,0 +1,41 @@
+// modules/storage/local-adapter.ts — Adapter de disco local
+// Almacena archivos en el sistema de archivos local
+
+import { mkdir, writeFile, unlink } from 'node:fs/promises'
+import { join, extname } from 'node:path'
+import type { StorageAdapter, FileUpload, StoredFile } from './index'
+
+export class LocalStorageAdapter implements StorageAdapter {
+  constructor(
+    private basePath: string = './uploads',
+    private baseUrl: string = '/uploads',
+  ) {}
+
+  async upload(file: FileUpload, directory?: string): Promise<StoredFile> {
+    const dir = directory ?? 'general'
+    const ext = extname(file.originalName)
+    const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`
+    const relativePath = `${dir}/${filename}`
+    const fullPath = join(this.basePath, relativePath)
+
+    await mkdir(join(this.basePath, dir), { recursive: true })
+    await writeFile(fullPath, file.buffer)
+
+    return {
+      url: `${this.baseUrl}/${relativePath}`,
+      path: relativePath,
+      originalName: file.originalName,
+      mimeType: file.mimeType,
+      size: file.size,
+    }
+  }
+
+  async delete(path: string): Promise<void> {
+    const fullPath = join(this.basePath, path)
+    await unlink(fullPath).catch(() => {})
+  }
+
+  getUrl(path: string): string {
+    return `${this.baseUrl}/${path}`
+  }
+}

package/modules/ws/__tests__/ws.test.ts

@@ -0,0 +1,114 @@
+// modules/ws/__tests__/ws.test.ts — Tests del WebSocket server
+// Prueba: handshake, parseFrame, sendFrame, broadcast, sendTo
+
+import { describe, it, expect } from 'bun:test'
+import { WSServer } from '../index'
+import { createHash } from 'node:crypto'
+
+// ─── Test de generateAccept ────────────────────────────
+describe('WSServer - handshake', () => {
+  it('generateAccept produce output correcto', () => {
+    // El WebSocket server tiene método generateAccept
+    // Probamos que devuelve un string base64 válido
+    const ws = new WSServer() as any
+    const key = 'dGhlIHNhbXBsZSBub25jZQ=='
+    const accept = ws.generateAccept(key)
+    expect(accept).toBeTruthy()
+    expect(typeof accept).toBe('string')
+    expect(accept.length).toBeGreaterThan(0)
+
+    // Verificar que el hash es correcto según RFC 6455
+    const expected = createHash('sha1').update(key + '258EAFA5-E914-47DA-95CA-5AB5DC11B725').digest('base64')
+    expect(accept).toBe(expected)
+  })
+})
+
+// ─── Test de parseFrame ────────────────────────────────
+describe('WSServer - parseFrame', () => {
+  it('parsea un frame de texto sin mask', () => {
+    const ws = new WSServer() as any
+    // Frame: FIN=1, opcode=1 (text), payload=Hola
+    const frame = Buffer.alloc(6)
+    frame[0] = 0x81       // FIN + texto
+    frame[1] = 4           // payload length
+    frame.write('Hola', 2) // payload
+    const result = ws.parseFrame(frame)
+    expect(result).toBe('Hola')
+  })
+
+  it('parsea un frame con mask', () => {
+    const ws = new WSServer() as any
+    const payload = Buffer.from('Hello')
+    const mask = Buffer.from([0x01, 0x02, 0x03, 0x04])
+    const masked = Buffer.alloc(payload.length)
+    for (let i = 0; i < payload.length; i++) {
+      masked[i] = (payload[i] ?? 0) ^ (mask[i % 4] ?? 0)
+    }
+
+    const frame = Buffer.alloc(2 + 4 + payload.length)
+    frame[0] = 0x81
+    frame[1] = 0x80 | payload.length  // MASK bit + length
+    mask.copy(frame, 2)
+    masked.copy(frame, 6)
+
+    const result = ws.parseFrame(frame)
+    expect(result).toBe('Hello')
+  })
+
+  it('devuelve null para frames no-texto', () => {
+    const ws = new WSServer() as any
+    // Frame: ping (opcode 0x09)
+    const frame = Buffer.alloc(2)
+    frame[0] = 0x89
+    frame[1] = 0
+    const result = ws.parseFrame(frame)
+    expect(result).toBeNull()
+  })
+})
+
+// ─── Test de sendFrame ────────────────────────────────
+describe('WSServer - sendFrame', () => {
+  it('construye frame correctamente', () => {
+    const ws = new WSServer() as any
+    const chunks: Buffer[] = []
+    const mockSocket = { write: (b: Buffer) => chunks.push(b) }
+
+    ws.sendFrame(mockSocket, 'Hola')
+    expect(chunks).toHaveLength(1)
+    const frame = chunks[0]!
+    expect(frame[0]).toBe(0x81)  // FIN + texto
+    expect(frame[1]).toBe(4)      // longitud
+    expect(frame.slice(2).toString()).toBe('Hola')
+  })
+})
+
+// ─── Test de broadcast ────────────────────────────────
+describe('WSServer - broadcast', () => {
+  it('envía a todos los clientes conectados', () => {
+    const ws = new WSServer() as any
+    const received: string[] = []
+
+    // Simular clientes conectados
+    ws.clients.set('c1', { id: 'c1', send: (d: string) => received.push(d), close: () => {} })
+    ws.clients.set('c2', { id: 'c2', send: (d: string) => received.push(d), close: () => {} })
+
+    ws.broadcast('test.event', { msg: 'hello' })
+    expect(received).toHaveLength(2)
+    expect(received[0]).toContain('test.event')
+    expect(received[1]).toContain('hello')
+  })
+})
+
+// ─── Test de sendTo ────────────────────────────────────
+describe('WSServer - sendTo', () => {
+  it('envía a un cliente específico', () => {
+    const ws = new WSServer() as any
+    const received: string[] = []
+
+    ws.clients.set('target', { id: 'target', send: (d: string) => received.push(d), close: () => {} })
+    ws.clients.set('other', { id: 'other', send: (d: string) => received.push(d), close: () => {} })
+
+    ws.sendTo('target', 'private.event', { secret: true })
+    expect(received).toHaveLength(1)
+  })
+})

package/modules/ws/index.ts

@@ -0,0 +1,136 @@
+// modules/ws/index.ts — WebSocket server (tiempo real)
+// Comunicación bidireccional entre servidor y clientes
+// Uso: WS en backend, EventSource o WS nativo en frontend
+
+import type { Server as HttpServer } from 'node:http'
+import { createHash } from 'node:crypto'
+
+export interface WSClient {
+  id: string
+  send(data: unknown): void
+  close(): void
+  onMessage(data: unknown): void
+  onClose(): void
+}
+
+export interface WSAdapter {
+  broadcast(event: string, data: unknown): void
+  sendTo(clientId: string, event: string, data: unknown): void
+  getClients(): WSClient[]
+}
+
+// ─── WebSocket nativo (sin dependencias externas) ───
+// Usa el servidor HTTP de Node. Para producción usar `ws` o `uWebSockets`.
+
+export class WSServer implements WSAdapter {
+  private clients = new Map<string, WSClient>()
+
+  attach(server: HttpServer): void {
+    server.on('upgrade', (req, socket, head) => {
+      // Implementación básica de WebSocket handshake
+      const key = req.headers['sec-websocket-key']
+      if (!key) { socket.destroy(); return }
+
+      const accept = this.generateAccept(key)
+      socket.write([
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${accept}`,
+        '',
+        '',
+      ].join('\r\n'))
+
+      const clientId = crypto.randomUUID()
+      const client: WSClient = {
+        id: clientId,
+        send: (data) => this.sendFrame(socket, JSON.stringify(data)),
+        close: () => socket.end(),
+        onMessage: () => {},
+        onClose: () => {},
+      }
+
+      this.clients.set(clientId, client)
+      console.log(`[WS] Client connected: ${clientId}`)
+
+      socket.on('data', (buffer) => {
+        const message = this.parseFrame(buffer)
+        if (message) client.onMessage(message)
+      })
+
+      socket.on('close', () => {
+        this.clients.delete(clientId)
+        client.onClose()
+        console.log(`[WS] Client disconnected: ${clientId}`)
+      })
+    })
+  }
+
+  broadcast(event: string, data: unknown): void {
+    const message = JSON.stringify({ event, data })
+    for (const client of this.clients.values()) {
+      try { client.send(message) } catch { /* ignore */ }
+    }
+  }
+
+  sendTo(clientId: string, event: string, data: unknown): void {
+    const client = this.clients.get(clientId)
+    if (client) {
+      client.send(JSON.stringify({ event, data }))
+    }
+  }
+
+  getClients(): WSClient[] {
+    return [...this.clients.values()]
+  }
+
+  private generateAccept(key: string): string {
+    const GUID = '258EAFA5-E914-47DA-95CA-5AB5DC11B725'
+    return createHash('sha1').update(key + GUID).digest('base64')
+  }
+
+  private sendFrame(socket: any, data: string): void {
+    const buffer = Buffer.from(data, 'utf-8')
+    const frame = Buffer.alloc(2 + buffer.length)
+    frame[0] = 0x81 // FIN + texto
+    frame[1] = buffer.length
+    buffer.copy(frame, 2)
+    socket.write(frame)
+  }
+
+  private parseFrame(buffer: Buffer): string | null {
+    if (buffer.length < 2) return null
+    const opcode = (buffer[0] ?? 0) & 0x0F
+    if (opcode !== 0x01) return null // solo texto
+    const masked = ((buffer[1] ?? 0) & 0x80) !== 0
+    let payloadLength = (buffer[1] ?? 0) & 0x7F
+    let offset = 2
+
+    if (payloadLength === 126) {
+      payloadLength = buffer.readUInt16BE(2)
+      offset = 4
+    } else if (payloadLength === 127) {
+      payloadLength = Number(buffer.readBigUInt64BE(2))
+      offset = 10
+    }
+
+    if (masked) {
+      const mask = buffer.slice(offset, offset + 4)
+      offset += 4
+      const payload = Buffer.alloc(payloadLength)
+      for (let i = 0; i < payloadLength; i++) {
+        payload[i] = (buffer[offset + i] ?? 0) ^ (mask[i % 4] ?? 0)
+      }
+      return payload.toString('utf-8')
+    }
+
+    return buffer.slice(offset, offset + payloadLength).toString('utf-8')
+  }
+}
+
+// ─── Uso en composition root ───────────────────────────
+// import { WSServer } from 'arckode-framework/modules/ws'
+// const ws = new WSServer()
+// ws.attach(http.server)
+//
+// ws.broadcast('pedido.nuevo', { id: '123' })

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "arckode-framework",
+  "version": "1.0.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",
+  "exports": {
+    ".": "./kernel/framework.ts",
+    "./middlewares": "./kernel/middlewares.ts",
+    "./static": "./kernel/static.ts",
+    "./events": "./modules/events/index.ts",
+    "./ws": "./modules/ws/index.ts",
+    "./adapters/sqlite": "./adapters/sqlite.ts",
+    "./adapters/jwt": "./adapters/jwt.ts",
+    "./adapters/postgres": "./adapters/postgres.ts",
+    "./adapters/redis-cache": "./adapters/redis-cache.ts",
+    "./adapters/mysql": "./adapters/mysql.ts",
+    "./modules/mail": "./modules/mail/index.ts",
+    "./modules/storage": "./modules/storage/index.ts",
+    "./modules/queue": "./modules/queue/index.ts",
+    "./testing": "./kernel/testing.ts"
+  },
+  "bin": {
+    "arckode": "bin/arckode.js"
+  },
+  "files": [
+    "bin/",
+    "kernel/",
+    "adapters/",
+    "modules/",
+    "cli/",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "arckode": "bun run cli/index.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "bunx tsc --noEmit",
+    "analyze:framework": "bun run cli/index.ts analyze"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3": ">=11.0.0",
+    "mysql2": ">=3.0.0",
+    "pg": ">=8.0.0",
+    "redis": ">=4.0.0",
+    "nodemailer": ">=6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/nodemailer": "^6.4.0",
+    "@types/pg": "^8.11.0",
+    "bun-types": "^1.3.14",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "framework",
+    "modular",
+    "SOLID",
+    "ai",
+    "bun",
+    "typescript",
+    "clean-architecture",
+    "composition-root",
+    "api",
+    "arckode"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/underworf/nexus-framework.git"
+  },
+  "homepage": "https://gitlab.com/underworf/nexus-framework#readme"
+}