arckode-framework 1.3.1 → 1.4.0

package/cli/stubs/module/core.ts

@@ -0,0 +1,162 @@
+import type { ModuleStubParams } from './types'
+import { mapTS } from './types'
+
+export function indexStub(p: ModuleStubParams): string {
+  const actions = ['list', 'getById', 'create', 'update', 'delete']
+  const events = [`on${p.name}Created`, `on${p.name}Updated`, `on${p.name}Deleted`]
+
+  return `// ${p.module}/index.ts — PUERTA PÚBLICA
+// Solo esto es visible para otros módulos y conectores.
+// ⚠ REGLA: Append-only. No sacar ni modificar exports existentes.
+
+import { createModule, OrmRepository } from 'arckode-framework'
+import { register${p.name}Models } from './model'
+import { ${p.name}Service } from './service'
+import { ${p.name}Controller } from './controller'
+import type { ${p.name}DTO } from './types'
+
+export { ${p.name}Service }
+export type { ${p.name}DTO, Create${p.name}DTO, Update${p.name}DTO, ${p.name}Query, ${p.name}Paginated } from './types'
+export type { ${p.name}Sockets } from './sockets'
+export { ${p.name}Validator, Create${p.name}Schema, Update${p.name}Schema } from './validators/schema'
+
+export function ${p.name}Module() {
+  return createModule({
+    name: '${p.module}',
+    version: '1.0.0',
+    description: 'Módulo de ${p.module}',
+
+    contract: {
+      name: '${p.module}',
+      version: '1.0.0',
+      description: 'Módulo de ${p.module}',
+      actions: ${JSON.stringify(actions)},
+      events: ${JSON.stringify(events)},
+      tables: ['${p.module}'],
+      dependencies: [],
+      rules: ['No importar de otros módulos'],
+    },
+
+    create({ logger, orm, cache, router, auth }) {
+      // Registrar modelo(s) — delegado a model.ts
+      register${p.name}Models(orm)
+
+      const repo = new OrmRepository<${p.name}DTO>(orm, '${p.name}')
+      const log = logger.child('${p.module}')
+      const service = new ${p.name}Service(repo, log, cache)
+      const controller = new ${p.name}Controller(service, log)
+
+      // Rutas públicas por defecto — agregar [auth.authenticate()] para proteger
+      router.get('/${p.module}', (req) => controller.index(req))
+      router.get('/${p.module}/:id', (req) => controller.show(req))
+      router.post('/${p.module}', (req) => controller.store(req))
+      router.put('/${p.module}/:id', (req) => controller.update(req))
+      router.delete('/${p.module}/:id', (req) => controller.destroy(req))
+
+      log.info('Módulo ${p.module} listo')
+      return service
+    },
+  })
+}
+`
+}
+
+export function modelStub(p: ModuleStubParams): string {
+  const modelFields = p.fields
+    .filter(f => !['id', 'createdAt', 'updatedAt', 'deletedAt'].includes(f.name))
+    .map(f => {
+      const parts = [`    ${f.name}: { type: '${f.type}'`]
+      if (f.required) parts.push(`, required: true`)
+      if (f.default !== undefined) parts.push(`, default: ${JSON.stringify(f.default)}`)
+      parts.push(` }`)
+      return parts.join('')
+    })
+    .join(',\n')
+
+  return `// ${p.module}/model.ts — Schema de base de datos
+// Responsabilidad ÚNICA: describir la estructura física de la tabla.
+// Importado por index.ts → orm.define() para registrar el modelo.
+//
+// Si el módulo tiene 3+ tablas, agregá registerModels(orm) acá y delegá desde index.ts.
+
+import type { ModelDefinition, ORM } from 'arckode-framework'
+
+export const ${p.name}Model: ModelDefinition = {
+  table: '${p.module}',
+  fields: {
+${modelFields}
+  },
+  timestamps: true,
+${p.softDelete ? '  softDelete: true,' : ''}
+}
+
+// Helper opcional — usalo si el módulo registra 3+ tablas
+// (mantiene index.ts limpio, enfocado en wiring)
+export function register${p.name}Models(orm: ORM): void {
+  orm.define('${p.name}', ${p.name}Model)
+}
+`
+}
+
+export function typesStub(p: ModuleStubParams): string {
+  const fields = p.fields.map(f => `  ${f.name}${f.required ? '' : '?'}: ${mapTS(f.type)}`).join('\n')
+  const filterFields = p.fields.map(f => `  ${f.name}?: ${mapTS(f.type)}`).join('\n')
+
+  return `// ${p.module}/types.ts — DTOs y tipos de queries
+// Responsabilidad ÚNICA: contrato TypeScript del módulo (cómo se ven los datos).
+// El schema de DB vive en ./model.ts — son conceptos distintos.
+
+export interface ${p.name}DTO {
+  id: string
+${fields}
+  createdAt: string
+  updatedAt: string
+${p.softDelete ? '  deletedAt: string | null' : ''}
+}
+
+export interface Create${p.name}DTO {
+${p.fields.filter(f => !f.name.match(/^(id|createdAt|updatedAt|deletedAt)$/)).map(f => `  ${f.name}${f.required ? '' : '?'}: ${mapTS(f.type)}`).join('\n')}
+}
+
+export interface Update${p.name}DTO {
+${p.fields.filter(f => !f.name.match(/^(id|createdAt|updatedAt|deletedAt)$/)).map(f => `  ${f.name}?: ${mapTS(f.type)}`).join('\n')}
+}
+
+// ─── Consultas y paginación ────────────────────────────
+export interface ${p.name}Query {
+${filterFields}
+  page?: number
+  limit?: number
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
+  search?: string
+}
+
+export interface ${p.name}Paginated {
+  data: ${p.name}DTO[]
+  pagination: {
+    page: number
+    limit: number
+    total: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+  }
+}
+`
+}
+
+export function socketsStub(p: ModuleStubParams): string {
+  return `// ${p.module}/sockets.ts — Hooks OPCIONALES hacia otros módulos
+// Los sockets son opcionales. El módulo funciona sin ellos.
+// Un conector puede pasar sockets para reaccionar a eventos del módulo.
+
+import type { ${p.name}DTO } from './types'
+
+export interface ${p.name}Sockets {
+  on${p.name}Created?: (data: ${p.name}DTO) => Promise<void>
+  on${p.name}Updated?: (data: ${p.name}DTO) => Promise<void>
+  on${p.name}Deleted?: (id: string) => Promise<void>
+}
+`
+}

package/cli/stubs/module/data.ts

@@ -0,0 +1,171 @@
+import type { ModuleStubParams } from './types'
+
+export function testStub(p: ModuleStubParams): string {
+  return `// ${p.module}/tests/service.test.ts — Tests del servicio
+// Usa RepositoryAdapter mock — sin dependencia de SQLite ni Postgres.
+
+import { describe, it, expect } from 'bun:test'
+import type { RepositoryAdapter, CacheAdapter } from 'arckode-framework'
+import { silentLogger } from 'arckode-framework/testing'
+import { ${p.name}Service } from '../service'
+import type { ${p.name}DTO } from '../types'
+
+// silentLogger es una factory function — SIEMPRE llamarla con ()
+const log = silentLogger()
+const silentCache: CacheAdapter = { get: async () => null, set: async () => {}, delete: async () => {}, clear: async () => {}, flush: async () => {} }
+
+function makeRepo(overrides: Partial<RepositoryAdapter<${p.name}DTO>> = {}): RepositoryAdapter<${p.name}DTO> {
+  return {
+    findMany: async () => [],
+    findById: async () => null,
+    findOne: async () => null,
+    create: async (data) => ({ id: 'test-id', ...data } as ${p.name}DTO),
+    update: async (id, data) => ({ id, ...data } as ${p.name}DTO),
+    delete: async () => true,
+    count: async () => 0,
+    paginate: async () => ({ data: [], total: 0, limit: 20, offset: 0, pages: 0 }),
+    ...overrides,
+  }
+}
+
+describe('${p.name}Service', () => {
+  describe('getById', () => {
+    it('lanza NotFound si el item no existe', async () => {
+      const service = new ${p.name}Service(makeRepo(), log, silentCache)
+      await expect(service.getById('no-existe')).rejects.toThrow('${p.name} no encontrado')
+    })
+
+    it('retorna el item si existe', async () => {
+      const item = { id: '1' } as ${p.name}DTO
+      const service = new ${p.name}Service(makeRepo({ findById: async () => item }), log, silentCache)
+      expect(await service.getById('1')).toEqual(item)
+    })
+  })
+
+  describe('create', () => {
+    it('crea y retorna el item', async () => {
+      const service = new ${p.name}Service(makeRepo(), log, silentCache)
+      const result = await service.create({} as any)
+      expect(result.id).toBe('test-id')
+    })
+  })
+
+  describe('delete', () => {
+    it('lanza NotFound si el item no existe', async () => {
+      const service = new ${p.name}Service(makeRepo({ delete: async () => false }), log, silentCache)
+      await expect(service.delete('no-existe')).rejects.toThrow('${p.name} no encontrado')
+    })
+  })
+})
+`
+}
+
+export function migrationStub(p: ModuleStubParams): string {
+  const sqlType = (f: ModuleStubParams['fields'][0]): string => {
+    if (f.name === 'id') return 'VARCHAR(36)'
+    const map: Record<string, string> = {
+      string:  'VARCHAR(255)',
+      number:  'DECIMAL(15,4)',
+      boolean: 'BOOLEAN',
+      date:    'TIMESTAMP',
+      json:    'TEXT',
+    }
+    return map[f.type] ?? 'TEXT'
+  }
+
+  const cols = p.fields.map(f => {
+    const pk  = f.name === 'id' ? ' PRIMARY KEY' : ''
+    const req = f.required && f.name !== 'id' ? ' NOT NULL' : ''
+    const def = f.default !== undefined ? ` DEFAULT ${typeof f.default === 'string' ? `'${f.default}'` : f.default}` : ''
+    return `      ${f.name} ${sqlType(f)}${pk}${req}${def}`
+  }).join('\n')
+
+  return `// migrations/${Date.now()}_create_${p.module}.ts
+// Migración generada por arckode make:module
+// SQL ANSI — compatible con SQLite, MySQL y Postgres sin modificaciones.
+import type { MigrationRunner } from 'arckode-framework/cli/commands/db-migrate'
+
+export async function up(db: MigrationRunner): Promise<void> {
+  await db.run(\`
+    CREATE TABLE IF NOT EXISTS ${p.module} (
+${cols},
+      createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+      updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP${p.softDelete ? ',\n      deletedAt TIMESTAMP NULL' : ''}
+    )
+  \`)
+}
+
+export async function down(db: MigrationRunner): Promise<void> {
+  await db.run(\`DROP TABLE IF EXISTS ${p.module}\`)
+}
+`
+}
+
+export function seedStub(p: ModuleStubParams): string {
+  const sampleData = p.fields
+    .filter(f => f.name !== 'id' && f.name !== 'createdAt' && f.name !== 'updatedAt')
+    .map(f => {
+      if (f.name === 'nombre' || f.name === 'name') return `    ${f.name}: '${p.name} de ejemplo'`
+      if (f.name === 'email') return `    ${f.name}: 'ejemplo@correo.com'`
+      if (f.name === 'activo' || f.name === 'active') return `    ${f.name}: true`
+      if (f.type === 'number') return `    ${f.name}: 100`
+      if (f.type === 'boolean') return `    ${f.name}: false`
+      return `    ${f.name}: 'valor'`
+    })
+    .join('\n')
+
+  return `// seeds/${p.module}.ts — Datos de prueba
+import type { SeedOrm } from 'arckode-framework/cli/commands/db-seed'
+
+export async function seed${p.name}(orm: SeedOrm): Promise<void> {
+  const items = [
+    {
+${sampleData}
+    },
+    {
+${sampleData.replace(`'${p.name} de ejemplo'`, `'${p.name} de ejemplo 2'`).replace(`'ejemplo@correo.com'`, `'ejemplo2@correo.com'`)}
+    },
+  ]
+
+  await Promise.all(items.map(item => orm.create('${p.name}', item)))
+
+  console.log('  ✓ ${p.name} seeded: ' + items.length + ' items')
+}
+`
+}
+
+// NO se genera por default. Crealo a mano cuando:
+//   1. El service repite los mismos filtros en varios métodos
+//   2. Necesitás queries con JOIN, IN, LIKE — el ORM builtin no las soporta
+//   3. Querés expresar la query en lenguaje del DOMINIO
+export function repositoryStub(p: ModuleStubParams): string {
+  return `// ${p.module}/repository.ts — Repository de dominio (OPCIONAL)
+// Encapsula queries con NOMBRES DEL DOMINIO en lugar de nombres de columna.
+//
+// Antes:  service.findOne({ user_id: userId, currency })   ← service conoce la DB
+// Ahora:  service.findByUserAndCurrency(userId, currency)  ← service habla el dominio
+//
+// Implementa RepositoryAdapter<${p.name}DTO> si necesitás queries complejas (JOIN, IN).
+
+import type { RepositoryAdapter } from 'arckode-framework'
+import type { ${p.name}DTO } from './types'
+
+export class ${p.name}Repository {
+  constructor(private readonly base: RepositoryAdapter<${p.name}DTO>) {}
+
+  // Métodos genéricos delegados al adapter base
+  findById(id: string)   { return this.base.findById(id) }
+  findMany(filters?: Record<string, unknown>) { return this.base.findMany(filters) }
+  create(data: Omit<${p.name}DTO, 'id'>) { return this.base.create(data) }
+  update(id: string, data: Partial<Omit<${p.name}DTO, 'id'>>) { return this.base.update(id, data) }
+  delete(id: string)     { return this.base.delete(id) }
+
+  // ─── Métodos específicos del dominio ───
+  // Agregá acá las queries que se repiten en el service
+  //
+  // async findActiveByUser(userId: string): Promise<${p.name}DTO[]> {
+  //   return this.base.findMany({ user_id: userId, active: true })
+  // }
+}
+`
+}

package/cli/stubs/module/index.ts

@@ -0,0 +1,5 @@
+export type { ModuleStubParams } from './types'
+export { mapTS } from './types'
+export { indexStub, modelStub, typesStub, socketsStub } from './core'
+export { serviceStub, controllerStub, validatorStub } from './service'
+export { testStub, migrationStub, seedStub, repositoryStub } from './data'

package/cli/stubs/module/service.ts

@@ -0,0 +1,198 @@
+import type { ModuleStubParams } from './types'
+
+export function serviceStub(p: ModuleStubParams): string {
+  return `// ${p.module}/service.ts — Facade pública del módulo
+// Responsabilidad ÚNICA: casos de uso del módulo.
+// NO sabe de HTTP. NO importa de otros módulos.
+// Recibe dependencias por constructor (Dependency Inversion).
+//
+// Si este archivo supera 200 líneas → extraer casos de uso a ./usecases/{caso}.ts
+// y dejar acá solo el orquestador que delega.
+//
+// IMPORTANTE: depende de RepositoryAdapter<${p.name}DTO>, no del ORM directamente.
+// Esto permite swapear SQL → MongoDB → Prisma en composition-root.ts sin tocar este archivo.
+
+import type { RepositoryAdapter, Logger, CacheAdapter } from 'arckode-framework'
+import { NotFoundError } from 'arckode-framework'
+import type { ${p.name}DTO, Create${p.name}DTO, Update${p.name}DTO, ${p.name}Query, ${p.name}Paginated } from './types'
+import type { ${p.name}Sockets } from './sockets'
+
+export class ${p.name}Service {
+  private sockets: ${p.name}Sockets = {}
+
+  constructor(
+    private readonly repo: RepositoryAdapter<${p.name}DTO>,
+    private readonly logger: Logger,
+    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 {
+    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> {
+    this.logger.info('Listando ${p.module}', { query })
+
+    const page = query?.page ?? 1
+    const limit = query?.limit ?? 20
+    const offset = (page - 1) * limit
+    const filters: Record<string, unknown> = {}
+
+    ${p.fields.filter(f => f.name !== 'id').slice(0, 3).map(f => `if (query?.${f.name} !== undefined) filters.${f.name} = query.${f.name}`).join('\n    ')}
+
+    const result = await this.repo.paginate(filters, { limit, offset })
+
+    return {
+      data: result.data,
+      pagination: {
+        page,
+        limit,
+        total: result.total,
+        totalPages: result.pages,
+        hasNext: offset + limit < result.total,
+        hasPrev: page > 1,
+      },
+    }
+  }
+
+  async getById(id: string): Promise<${p.name}DTO> {
+    this.logger.info('Obteniendo ${p.module}', { id })
+    const item = await this.repo.findById(id)
+    if (!item) throw new NotFoundError('${p.name} no encontrado')
+    // IDOR: si el recurso tiene userId u ownerId, descomentar y adaptar:
+    // auth.assertOwnership(item.userId as string, currentUser.id, currentUser.role)
+    return item
+  }
+
+  async create(dto: Create${p.name}DTO): Promise<${p.name}DTO> {
+    this.logger.info('Creando ${p.module}')
+    const item = await this.repo.create(dto as Omit<${p.name}DTO, 'id'>)
+    await this.sockets.on${p.name}Created?.(item)
+    await this.cache.delete('${p.module}:list')
+    return item
+  }
+
+  async update(id: string, dto: Update${p.name}DTO): Promise<${p.name}DTO> {
+    this.logger.info('Actualizando ${p.module}', { id })
+    const item = await this.repo.update(id, dto as Partial<Omit<${p.name}DTO, 'id'>>)
+    if (!item) throw new NotFoundError('${p.name} no encontrado')
+    await this.sockets.on${p.name}Updated?.(item)
+    await this.cache.delete('${p.module}:list')
+    return item
+  }
+
+  async delete(id: string): Promise<void> {
+    this.logger.info('Eliminando ${p.module}', { id })
+    const deleted = await this.repo.delete(id)
+    if (!deleted) throw new NotFoundError('${p.name} no encontrado')
+    await this.sockets.on${p.name}Deleted?.(id)
+    await this.cache.delete('${p.module}:list')
+  }
+}
+`
+}
+
+export function controllerStub(p: ModuleStubParams): string {
+  return `// ${p.module}/controller.ts — Adaptador HTTP del módulo
+// Responsabilidad ÚNICA: traducir request → service → response.
+// SIN lógica de negocio. SIN llamadas directas al ORM. (REGLA #12)
+// Toda mutación (POST/PUT/PATCH) DEBE pasar por validateSchema(). (REGLA #11)
+
+import type { HttpRequest, Logger } from 'arckode-framework'
+import { validateSchema } from 'arckode-framework'
+import type { ${p.name}Service } from './service'
+import { Create${p.name}Schema, Update${p.name}Schema } from './validators/schema'
+
+export class ${p.name}Controller {
+  constructor(
+    private readonly service: ${p.name}Service,
+    private readonly logger: Logger,
+  ) {}
+
+  async index(req: HttpRequest) {
+    this.logger.info('GET /${p.module}')
+    const result = await this.service.list(req.query as any)
+    return { status: 200, body: result }
+  }
+
+  async show(req: HttpRequest) {
+    this.logger.info('GET /${p.module}/:id', { id: req.params.id })
+    const item = await this.service.getById(req.params.id)
+    return { status: 200, body: item }
+  }
+
+  async store(req: HttpRequest) {
+    this.logger.info('POST /${p.module}')
+    const data = validateSchema(Create${p.name}Schema, req.body)
+    const item = await this.service.create(data as any)
+    return { status: 201, body: item }
+  }
+
+  async update(req: HttpRequest) {
+    this.logger.info('PUT /${p.module}/:id', { id: req.params.id })
+    const data = validateSchema(Update${p.name}Schema, req.body)
+    const item = await this.service.update(req.params.id, data as any)
+    return { status: 200, body: item }
+  }
+
+  async destroy(req: HttpRequest) {
+    this.logger.info('DELETE /${p.module}/:id', { id: req.params.id })
+    await this.service.delete(req.params.id)
+    return { status: 204, body: null }
+  }
+}
+`
+}
+
+export function validatorStub(p: ModuleStubParams): string {
+  const createRules = p.fields
+    .filter(f => f.name !== 'id')
+    .map(f => {
+      const parts = [`  ${f.name}: { type: '${f.type}' as const`]
+      if (f.required && f.name !== 'createdAt' && f.name !== 'updatedAt') parts.push(', required: true')
+      if (f.type === 'string' && f.required) parts.push(', min: 2, max: 200')
+      parts.push(' }')
+      return parts.join('')
+    })
+    .join(',\n')
+
+  const updateRules = p.fields
+    .filter(f => f.name !== 'id' && f.name !== 'createdAt')
+    .map(f => {
+      const parts = [`  ${f.name}: { type: '${f.type}' as const`]
+      if (f.type === 'string') parts.push(', min: 2, max: 200')
+      parts.push(' }')
+      return parts.join('')
+    })
+    .join(',\n')
+
+  return `// ${p.module}/validators/schema.ts — Validación de entrada
+// Schemas planos, sin dependencias externas.
+
+import type { ValidationRule } from 'arckode-framework'
+
+export const Create${p.name}Schema: Record<string, ValidationRule> = {
+${createRules}
+}
+
+export const Update${p.name}Schema: Record<string, ValidationRule> = {
+${updateRules}
+}
+
+// Schema compuesto para usar en validación directa
+export const ${p.name}Validator = {
+  create: Create${p.name}Schema,
+  update: Update${p.name}Schema,
+}
+`
+}

package/cli/stubs/module/types.ts

@@ -0,0 +1,12 @@
+export interface ModuleStubParams {
+  name: string
+  module: string
+  fields: { name: string; type: 'string' | 'number' | 'boolean' | 'date'; required: boolean; default?: unknown }[]
+  relations?: { type: 'hasMany' | 'belongsTo'; model: string; foreignKey: string }[]
+  softDelete?: boolean
+}
+
+export function mapTS(type: string): string {
+  const map: Record<string, string> = { string: 'string', number: 'number', boolean: 'boolean', date: 'string' }
+  return map[type] ?? 'unknown'
+}