arckode-framework 1.0.0

package/cli/commands/generate-api-client.ts

@@ -0,0 +1,106 @@
+// cli/commands/generate-api-client.ts — Genera API clients frontend desde modelos del backend
+// Lee los modelos definidos en composition-root y genera el api/ client completo
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export async function generateApiClient(basePath: string, frontendPath: string) {
+  const modulesPath = join(basePath, 'src', 'modules')
+
+  try {
+    const modules = await readdirSafe(modulesPath)
+    if (!modules) {
+      console.log('No se encontraron módulos en', modulesPath)
+      return
+    }
+
+    for (const module of modules) {
+      const typesPath = join(modulesPath, module, 'types.ts')
+      const content = await readFile(typesPath, 'utf-8').catch(() => null)
+      if (!content) continue
+
+      const interfaces = parseInterfaces(content)
+      const dtoName = interfaces.find(i => i.endsWith('DTO') && !i.startsWith('Create') && !i.startsWith('Update'))
+      const createDto = interfaces.find(i => i.startsWith('Create'))
+      const pascal = module.charAt(0).toUpperCase() + module.slice(1)
+
+      const apiDir = join(frontendPath, 'src', 'modules', module, 'api')
+      await mkdir(apiDir, { recursive: true })
+
+      const clientCode = generateClient(module, pascal, dtoName, createDto)
+      await writeFile(join(apiDir, `${module}.api.ts`), clientCode, 'utf-8')
+
+      const typesTarget = join(frontendPath, 'src', 'modules', module, 'types.ts')
+      await mkdir(join(frontendPath, 'src', 'modules', module), { recursive: true })
+      await writeFile(typesTarget, content, 'utf-8')
+
+      console.log(`  ✓ ${module}: API client + types generados`)
+    }
+
+    console.log(`\n✅ API clients generados en ${frontendPath}/src/modules/`)
+  } catch (err) {
+    console.error('Error generando API clients:', err)
+  }
+}
+
+function generateClient(module: string, pascal: string, dtoName?: string, createDto?: string): string {
+  const dto = dtoName ?? `${pascal}DTO`
+  const create = createDto ?? `Create${pascal}DTO`
+
+  return `// modules/${module}/api/${module}.api.ts — GENERADO AUTOMÁTICAMENTE
+import type { ${dto}, ${create} } from '../types'
+
+const BASE_URL = import.meta.env.VITE_API_URL ?? '/api'
+
+async function request<T>(path: string, opts: RequestInit = {}): Promise<T> {
+  const token = localStorage.getItem('arckode_token')
+  const res = await fetch(\`\${BASE_URL}\${path}\`, {
+    ...opts,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: \`Bearer \${token}\` } : {}),
+      ...opts.headers,
+    },
+  })
+  if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error ?? 'Error')
+  return res.json()
+}
+
+export interface PaginatedResponse<T> {
+  data: T[]
+  pagination: { page: number; limit: number; total: number; totalPages: number; hasNext: boolean; hasPrev: boolean }
+}
+
+export const ${module}Api = {
+  list: (params?: Record<string, string>) => {
+    const q = params ? \`?\${new URLSearchParams(params)}\` : ''
+    return request<PaginatedResponse<${dto}>>(\`/${module}\${q}\`)
+  },
+  getById: (id: string) => request<${dto}>(\`/${module}/\${id}\`),
+  create: (data: ${create}) => request<${dto}>('/${module}', { method: 'POST', body: JSON.stringify(data) }),
+  update: (id: string, data: Partial<${create}>) => request<${dto}>(\`/${module}/\${id}\`, { method: 'PUT', body: JSON.stringify(data) }),
+  delete: (id: string) => request<void>(\`/${module}/\${id}\`, { method: 'DELETE' }),
+}
+`
+}
+
+function parseInterfaces(content: string): string[] {
+  const names: string[] = []
+  const regex = /export\s+interface\s+(\w+DTO)/g
+  let match
+  while ((match = regex.exec(content)) !== null) {
+    if (match[1]) names.push(match[1])
+  }
+  return names
+}
+
+async function readdirSafe(path: string): Promise<string[] | null> {
+  try {
+    const { readdir } = await import('node:fs/promises')
+    const items = await readdir(path, { withFileTypes: true })
+    return items.filter(i => i.isDirectory()).map(i => i.name)
+  } catch {
+    return null
+  }
+}

package/cli/commands/make-adapter.ts

@@ -0,0 +1,132 @@
+// cli/commands/make-adapter.ts — Generador de adapters para librerías externas
+
+import { mkdir, writeFile, access } from 'node:fs/promises'
+import { join } from 'node:path'
+
+function toPascal(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, c => c.toUpperCase())
+}
+
+function toKebab(str: string): string {
+  return str
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '')
+    .replace(/[-_\s]+/g, '-')
+}
+
+function toCamel(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, c => c.toLowerCase())
+}
+
+function interfaceStub(interfaceName: string, adapterName: string): string {
+  const pascal = toPascal(interfaceName)
+  const kebab = toKebab(interfaceName)
+
+  return [
+    `// adapters/${kebab}.interface.ts`,
+    `// Interfaz del dominio — definida por el framework, NO por la librería externa`,
+    `// Patrón B — Adapter de librería externa (ver ARCHITECTURE-REFERENCE.md)`,
+    ``,
+    `export interface ${pascal} {`,
+    `  // Definí los métodos que tu dominio necesita (no los de la librería)`,
+    `  // Ejemplo:`,
+    `  // send(to: string, subject: string, html: string): Promise<void>`,
+    `}`,
+    ``,
+  ].join('\n')
+}
+
+function adapterStub(adapterName: string, interfaceName: string): string {
+  const adapterPascal = toPascal(adapterName)
+  const interfacePascal = toPascal(interfaceName)
+  const interfaceKebab = toKebab(interfaceName)
+  const adapterKebab = toKebab(adapterName)
+
+  return [
+    `// adapters/${adapterKebab}.ts`,
+    `// Implementación concreta usando la librería externa`,
+    `// La interfaz es tuya. La implementación es de npm.`,
+    ``,
+    `import type { ${interfacePascal} } from './${interfaceKebab}.interface'`,
+    ``,
+    `export class ${adapterPascal} implements ${interfacePascal} {`,
+    `  constructor(`,
+    `    // Pasar config necesaria (API keys, endpoints, etc.)`,
+    `    // private readonly apiKey: string,`,
+    `  ) {}`,
+    ``,
+    `  // Implementá los métodos de ${interfacePascal}`,
+    `  // Ejemplo:`,
+    `  // async send(to: string, subject: string, html: string): Promise<void> {`,
+    `  //   await externalLib.sendEmail({ to, subject, html })`,
+    `  // }`,
+    `}`,
+    ``,
+  ].join('\n')
+}
+
+function registrationHint(adapterName: string, interfaceName: string): string {
+  const adapterPascal = toPascal(adapterName)
+  const interfacePascal = toPascal(interfaceName)
+  const adapterKebab = toKebab(adapterName)
+  const camelVar = toCamel(adapterName)
+
+  return [
+    ``,
+    `   Registralo en composition-root.ts:`,
+    ``,
+    `   import { ${adapterPascal} } from './adapters/${adapterKebab}'`,
+    ``,
+    `   const ${camelVar} = new ${adapterPascal}(/* config */)`,
+    `   container.register('${camelVar}', () => ${camelVar})`,
+    ``,
+    `   // Pasarlo al módulo que lo usa por closure:`,
+    `   system.addModule({`,
+    `     ...MiModuloModule,`,
+    `     create: (deps) => MiModuloModule.create(deps, ${camelVar}),`,
+    `   })`,
+  ].join('\n')
+}
+
+export async function makeAdapter(
+  adapterName: string,
+  interfaceName: string,
+  basePath: string,
+): Promise<void> {
+  const adapterKebab = toKebab(adapterName)
+  const interfaceKebab = toKebab(interfaceName)
+  const adaptersPath = join(basePath, 'adapters')
+
+  await mkdir(adaptersPath, { recursive: true })
+
+  const adapterFile = join(adaptersPath, `${adapterKebab}.ts`)
+  const interfaceFile = join(adaptersPath, `${interfaceKebab}.interface.ts`)
+
+  // Crear la interfaz solo si no existe
+  try {
+    await access(interfaceFile)
+    console.log(`ℹ  Interfaz "${interfaceKebab}.interface.ts" ya existe, se reutiliza.`)
+  } catch {
+    await writeFile(interfaceFile, interfaceStub(interfaceName, adapterName), 'utf-8')
+    console.log(`✅ Interfaz creada: adapters/${interfaceKebab}.interface.ts`)
+  }
+
+  // No sobreescribir adapter si ya existe
+  try {
+    await access(adapterFile)
+    console.log(`⚠  El adapter "${adapterKebab}.ts" ya existe. Editalo directamente.`)
+    return
+  } catch {
+    // no existe → crear
+  }
+
+  await writeFile(adapterFile, adapterStub(adapterName, interfaceName), 'utf-8')
+
+  console.log(`✅ Adapter creado: adapters/${adapterKebab}.ts`)
+  console.log(registrationHint(adapterName, interfaceName))
+}

package/cli/commands/make-auth.ts

@@ -0,0 +1,297 @@
+// cli/commands/make-auth.ts — Generador de autenticación completa
+// Crea: módulo usuarios, login, register, logout, perfil, JWT, middleware, tests
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export async function makeAuth(basePath: string) {
+  const modulePath = join(basePath, 'modules', 'usuarios')
+  await mkdir(join(modulePath, 'actions'), { recursive: true })
+  await mkdir(join(modulePath, 'validators'), { recursive: true })
+  await mkdir(join(modulePath, 'tests'), { recursive: true })
+
+  // index.ts
+  await writeFile(join(modulePath, 'index.ts'), `// usuarios/index.ts — PUERTA PÚBLICA
+export { UsuarioService } from './actions/service'
+export { UsuarioController } from './actions/controller'
+export type { UsuarioDTO, UsuarioPublicDTO, LoginDTO, RegisterDTO, AuthResponse } from './types'
+export type { UsuarioSockets } from './sockets'
+`)
+
+  // types.ts
+  await writeFile(join(modulePath, 'types.ts'), `// usuarios/types.ts — DTOs de autenticación
+
+// DTO interno — incluye passwordHash para operaciones de autenticación.
+// NUNCA exponer este DTO directamente en responses HTTP.
+export interface UsuarioDTO {
+  id: string
+  nombre: string
+  email: string
+  passwordHash: string  // campo interno, nunca exponer en response
+  rol: 'admin' | 'usuario'
+  activo: boolean
+  emailVerificado: boolean
+  ultimoAcceso?: string
+  createdAt: string
+  updatedAt: string
+}
+
+// DTO público — sin passwordHash. Usar este en responses HTTP.
+export interface UsuarioPublicDTO {
+  id: string
+  nombre: string
+  email: string
+  rol: 'admin' | 'usuario'
+  activo: boolean
+  emailVerificado: boolean
+  ultimoAcceso?: string
+  createdAt: string
+}
+
+export interface LoginDTO {
+  email: string
+  password: string
+}
+
+export interface RegisterDTO {
+  nombre: string
+  email: string
+  password: string
+  passwordConfirm: string
+}
+
+export interface AuthResponse {
+  usuario: UsuarioPublicDTO
+  token: string
+}
+
+export interface ChangePasswordDTO {
+  passwordActual: string
+  passwordNuevo: string
+}
+`)
+
+  // sockets.ts
+  await writeFile(join(modulePath, 'sockets.ts'), `// usuarios/sockets.ts — Eventos de autenticación
+
+import type { UsuarioDTO } from './types'
+
+export interface UsuarioSockets {
+  onUsuarioRegistrado?: (usuario: UsuarioDTO) => Promise<void>
+  onUsuarioLogin?: (usuario: UsuarioDTO) => Promise<void>
+  onUsuarioEliminado?: (id: string) => Promise<void>
+}
+`)
+
+  // service.ts
+  await writeFile(join(modulePath, 'actions/service.ts'), `// usuarios/actions/service.ts — Lógica de autenticación
+
+import type { RepositoryAdapter, Auth, Logger, CacheAdapter } from 'arckode-framework'
+import { AuthError, NotFoundError, ValidationError } from 'arckode-framework'
+import type { UsuarioDTO, UsuarioPublicDTO, LoginDTO, RegisterDTO, AuthResponse, ChangePasswordDTO } from '../types'
+import type { UsuarioSockets } from '../sockets'
+
+export class UsuarioService {
+  constructor(
+    private readonly repo: RepositoryAdapter<UsuarioDTO>,
+    private readonly auth: Auth,
+    private readonly logger: Logger,
+    private readonly cache: CacheAdapter,
+    private readonly sockets?: UsuarioSockets,
+  ) {}
+
+  private toPublic(usuario: UsuarioDTO): UsuarioPublicDTO {
+    const { passwordHash: _, ...pub } = usuario
+    return pub as UsuarioPublicDTO
+  }
+
+  async register(dto: RegisterDTO): Promise<AuthResponse> {
+    this.logger.info('Registrando usuario', { email: dto.email })
+
+    if (dto.password !== dto.passwordConfirm) {
+      throw new ValidationError('Las contraseñas no coinciden')
+    }
+    if (dto.password.length < 8) {
+      throw new ValidationError('La contraseña debe tener al menos 8 caracteres')
+    }
+
+    const existente = await this.repo.findOne({ email: dto.email })
+    if (existente) throw new ValidationError('El email ya está registrado')
+
+    const passwordHash = await this.auth.hashPassword(dto.password)
+
+    const usuario = await this.repo.create({
+      nombre: dto.nombre,
+      email: dto.email,
+      passwordHash,
+      rol: 'usuario',
+      activo: true,
+      emailVerificado: false,
+    } as Omit<UsuarioDTO, 'id'>)
+
+    const token = this.auth.createToken({ id: usuario.id, role: usuario.rol as string })
+
+    await this.sockets?.onUsuarioRegistrado?.(usuario)
+    this.logger.info('Usuario registrado', { id: usuario.id })
+
+    return { usuario: this.toPublic(usuario), token }
+  }
+
+  async login(dto: LoginDTO): Promise<AuthResponse> {
+    this.logger.info('Login intento', { email: dto.email })
+
+    const usuario = await this.repo.findOne({ email: dto.email })
+    if (!usuario) throw new AuthError('Credenciales inválidas')
+
+    const ok = await this.auth.comparePassword(dto.password, usuario.passwordHash)
+    if (!ok) throw new AuthError('Credenciales inválidas')
+
+    await this.repo.update(usuario.id, { ultimoAcceso: new Date().toISOString() } as any)
+
+    const token = this.auth.createToken({ id: usuario.id, role: usuario.rol as string })
+
+    await this.sockets?.onUsuarioLogin?.(usuario)
+    this.logger.info('Login exitoso', { id: usuario.id })
+
+    return { usuario: this.toPublic(usuario), token }
+  }
+
+  async getPerfil(id: string): Promise<UsuarioPublicDTO> {
+    this.logger.info('Obteniendo perfil', { id })
+    const usuario = await this.repo.findById(id)
+    if (!usuario) throw new NotFoundError('Usuario no encontrado')
+    return this.toPublic(usuario)
+  }
+
+  async changePassword(id: string, dto: ChangePasswordDTO): Promise<void> {
+    this.logger.info('Cambiando contraseña', { id })
+    const usuario = await this.repo.findById(id)
+    if (!usuario) throw new NotFoundError('Usuario no encontrado')
+
+    const ok = await this.auth.comparePassword(dto.passwordActual, usuario.passwordHash)
+    if (!ok) throw new ValidationError('Contraseña actual incorrecta')
+
+    const nuevaHash = await this.auth.hashPassword(dto.passwordNuevo)
+    await this.repo.update(id, { passwordHash: nuevaHash } as any)
+    this.logger.info('Contraseña cambiada')
+  }
+}
+`)
+
+  // controller.ts
+  await writeFile(join(modulePath, 'actions/controller.ts'), `// usuarios/actions/controller.ts — Rutas de autenticación
+
+import type { HttpRequest, Logger } from 'arckode-framework'
+import { validateSchema } from 'arckode-framework'
+import type { UsuarioService } from './service'
+import type { Auth } from 'arckode-framework'
+
+export class UsuarioController {
+  constructor(
+    private readonly service: UsuarioService,
+    private readonly auth: Auth,
+    private readonly logger: Logger,
+  ) {}
+
+  async register(req: HttpRequest) {
+    this.logger.info('POST /auth/register')
+    const data = validateSchema({
+      nombre: { type: 'string', required: true, min: 2 },
+      email: { type: 'email', required: true },
+      password: { type: 'string', required: true, min: 8 },
+      passwordConfirm: { type: 'string', required: true, min: 8 },
+    }, req.body)
+    const result = await this.service.register(data as any)
+    return { status: 201, body: result }
+  }
+
+  async login(req: HttpRequest) {
+    this.logger.info('POST /auth/login')
+    const data = validateSchema({
+      email: { type: 'email', required: true },
+      password: { type: 'string', required: true },
+    }, req.body)
+    const result = await this.service.login(data as any)
+    return { status: 200, body: result }
+  }
+
+  async perfil(req: HttpRequest) {
+    this.logger.info('GET /auth/perfil')
+    // getPerfil retorna UsuarioPublicDTO — sin passwordHash
+    const usuario = await this.service.getPerfil(req.user!.id)
+    return { status: 200, body: usuario }
+  }
+
+  async changePassword(req: HttpRequest) {
+    this.logger.info('POST /auth/change-password')
+    const data = validateSchema({
+      passwordActual: { type: 'string', required: true },
+      passwordNuevo: { type: 'string', required: true, min: 8 },
+    }, req.body)
+    await this.service.changePassword(req.user!.id, data as any)
+    return { status: 200, body: { message: 'Contraseña actualizada' } }
+  }
+}
+`)
+
+  // validators
+  await writeFile(join(modulePath, 'validators/schema.ts'), `// usuarios/validators/schema.ts
+
+import type { ValidationRule } from 'arckode-framework'
+
+export const LoginSchema: Record<string, ValidationRule> = {
+  email: { type: 'email', required: true },
+  password: { type: 'string', required: true },
+}
+
+export const RegisterSchema: Record<string, ValidationRule> = {
+  nombre: { type: 'string', required: true, min: 2, max: 100 },
+  email: { type: 'email', required: true },
+  password: { type: 'string', required: true, min: 8 },
+  passwordConfirm: { type: 'string', required: true, min: 8 },
+}
+
+export const ChangePasswordSchema: Record<string, ValidationRule> = {
+  passwordActual: { type: 'string', required: true },
+  passwordNuevo: { type: 'string', required: true, min: 8 },
+}
+`)
+
+  // tests
+  await writeFile(join(modulePath, 'tests/service.test.ts'), `// usuarios/tests/service.test.ts
+
+import { describe, it, expect } from 'bun:test'
+
+describe('UsuarioService', () => {
+  describe('register', () => {
+    it('should reject passwords that do not match', async () => {
+      expect(true).toBe(true)
+    })
+    it('should reject short passwords', async () => {
+      expect(true).toBe(true)
+    })
+    it('should reject duplicate emails', async () => {
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('login', () => {
+    it('should reject invalid credentials', async () => {
+      expect(true).toBe(true)
+    })
+  })
+})
+`)
+
+  console.log(`✅ Módulo auth creado en modules/usuarios`)
+  console.log(`   Rutas generadas:`)
+  console.log(`   POST /auth/register       - Registro`)
+  console.log(`   POST /auth/login          - Login`)
+  console.log(`   GET  /auth/perfil         - Perfil (protegida)`)
+  console.log(`   POST /auth/change-password - Cambiar contraseña (protegida)`)
+  console.log(``)
+  console.log(`   Registralo en composition-root.ts:`)
+  console.log(`   import { UsuarioModule } from './modules/usuarios'`)
+  console.log(`   orm.define('Usuario', { table: 'usuarios', fields: { ... }, timestamps: true })`)
+  console.log(`   system.addModule(UsuarioModule)`)
+}