arckode-framework 1.0.7 → 1.1.0

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

@@ -0,0 +1,174 @@
+// cli/stubs/claude-md-stub.ts — Plantilla del CLAUDE.md generado por `arckode new`
+//
+// IMPORTANTE: Este archivo debe mantenerse SINCRONIZADO con CLAUDE.md del framework.
+// Si agregás/modificás una regla en /CLAUDE.md → actualizá también este stub.
+// Los proyectos NUEVOS lo reciben hardcoded en su raíz al ejecutar `arckode new`.
+
+export interface ClaudeMdStubParams {
+  projectName: string
+  db: 'sqlite' | 'mysql' | 'postgres'
+}
+
+export function claudeMdStub(p: ClaudeMdStubParams): string {
+  return `# CLAUDE.md — ${p.projectName}
+
+## Lee esto ANTES de escribir cualquier línea de código.
+
+### PASO 0 — Cargar contexto
+1. Si existe \`arckode.json\` → leelo (snapshot del sistema: módulos, conectores, violaciones).
+   Si no existe (proyecto recién creado), generalo con: \`bun run analyze:json\`
+2. Leer \`src/composition-root.ts\` → es la única fuente de verdad del sistema.
+3. Leer este CLAUDE.md → reglas inmutables y estructura obligatoria.
+
+---
+
+## Estructura obligatoria de un módulo
+
+\`\`\`
+src/modules/mi-modulo/
+  index.ts            ← OBLIGATORIO — factory: registra modelo via registerXxxModels, wirea rutas
+  model.ts            ← OBLIGATORIO — ModelDefinition (schema DB) + registerXxxModels(orm)
+  types.ts            ← OBLIGATORIO — DTOs y tipos de queries (sin schema DB)
+  sockets.ts          ← OBLIGATORIO — interfaz de eventos hacia otros módulos
+  service.ts          ← OBLIGATORIO — facade del módulo (lógica de negocio)
+  controller.ts       ← OBLIGATORIO — adaptador HTTP
+  repository.ts       ← OPCIONAL — queries con nombres del dominio (ver Regla #21)
+  usecases/           ← OPCIONAL — solo si hay 3+ flujos DIFERENTES (no CRUD)
+  validators/schema.ts ← OBLIGATORIO — esquemas de validateSchema()
+  tests/service.test.ts ← OBLIGATORIO — mínimo 2 casos (happy path + error)
+\`\`\`
+
+**\`service.ts\` y \`controller.ts\` van al ROOT del módulo, NO en \`actions/\`.**
+**\`model.ts\` separado de \`types.ts\`** porque schema DB y contrato TS son conceptos distintos.
+
+---
+
+## Reglas INMUTABLES (no se negocian, no se omiten)
+
+| # | Regla | Detección |
+|---|-------|-----------|
+| 1 | Módulos NO importan de otros módulos → usar conectores | \`arckode analyze\` |
+| 2 | index.ts es APPEND-ONLY → no eliminar exports existentes | manual |
+| 3 | Conectores NO tienen lógica de negocio → solo delegan | \`arckode analyze\` |
+| 4 | Cada tabla pertenece a UN módulo | manual |
+| 5 | Si no está en composition-root.ts, no existe | \`arckode analyze\` |
+| 6 | Todo POST/PUT/PATCH requiere validateSchema() | \`arckode analyze\` |
+| 7 | Controller NO llama al ORM → llama al service | \`arckode analyze\` |
+| 8 | Toda operación atómica multi-tabla usa Transactor (no inyectar ORM) | manual |
+| 9 | findById → verificar ownership inmediatamente (IDOR) | \`arckode analyze\` |
+| 10 | ORM dentro de un loop → N+1 prohibido | \`arckode analyze\` |
+| 11 | Service recibe RepositoryAdapter<T> o Repository del dominio, NO ORM directo | \`arckode analyze\` |
+| 15 | Extraer a usecases/ solo si hay 3+ flujos DIFERENTES (CRUD nunca se fragmenta) | manual |
+| 19 | Transactor para atomicidad multi-tabla — \`transactor.run(async (repos) => ...)\` | manual |
+| 20 | Conectores limpios: kebab-case, con prefijo \`connect\`, registrados en composition-root | \`arckode analyze\` |
+| 21 | Si el service repite filtros 3+ veces o necesita JOIN/IN/LIKE → crear \`repository.ts\` | manual |
+| 22 | \`model.ts\` separado de \`types.ts\` (schema DB ≠ contrato TS) | manual |
+
+---
+
+## Protocolo de la IA (4 pasos obligatorios)
+
+\`\`\`
+PASO 1 — IDENTIFICAR ALCANCE
+  ¿Toca 1 módulo? → Seguir
+  ¿Toca 1 conector? → Seguir
+  ¿Toca 2+ módulos? → DETENERSE. Dividir la tarea.
+
+PASO 2 — VERIFICAR REGLAS
+  ¿Importo de otro módulo? → NO (usar conector)
+  ¿Modifico index.ts? → Solo append
+  ¿Pongo lógica en el conector? → NO
+  ¿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 4 — VERIFICAR
+  bun run analyze --json → violations: 0
+  bun test → 0 fallos
+\`\`\`
+
+---
+
+## Patrones de código
+
+### Atomicidad multi-tabla — usar Transactor
+\`\`\`ts
+import type { Transactor, RepositoryAdapter } from 'arckode-framework'
+
+class WalletsService {
+  constructor(
+    private walletRepo: RepositoryAdapter<WalletDTO>,
+    private transactor: Transactor,
+  ) {}
+
+  async credit(userId: string, amount: number) {
+    await this.transactor.run(async (repos) => {
+      const wallets = repos.for<WalletDTO>('Wallet')
+      const txs    = repos.for<TransactionDTO>('Transaction')
+      await wallets.update(id, { balance })
+      await txs.create({ ... })
+    })
+  }
+}
+
+// composition-root:
+const transactor = new OrmTransactor(orm)
+\`\`\`
+
+### Repository del dominio (cuando aplique)
+\`\`\`ts
+// repository.ts — opcional, encapsula queries con nombres del dominio
+export class WalletsRepository {
+  constructor(private base: RepositoryAdapter<WalletDTO>) {}
+
+  findByUserAndCurrency(userId: string, currency: WalletCurrency) {
+    return this.base.findOne({ user_id: userId, currency })
+  }
+}
+
+// service.ts — habla en lenguaje del dominio, no de columnas
+const wallet = await this.wallets.findByUserAndCurrency(userId, currency)
+\`\`\`
+
+---
+
+## DB Adapter activo: \`${p.db}\`
+
+## Estructura del proyecto
+\`\`\`
+src/
+  composition-root.ts    ← TODO el sistema (módulos, conectores, infra)
+  modules/               ← módulos independientes (NO se importan entre sí)
+  connectors/            ← puentes entre módulos (sin lógica de negocio)
+  shared/helpers/        ← funciones puras sin estado
+  shared/services/       ← servicios con estado compartidos
+seeds/                   ← datos de prueba
+migrations/              ← migraciones explícitas de DB
+\`\`\`
+
+## Comandos útiles
+\`\`\`bash
+bun run dev                              # desarrollo con hot reload
+bun run analyze                          # verificar arquitectura (consola)
+bun run analyze:json                     # generar/actualizar arckode.json
+bun arckode make:module Nombre           # generar módulo completo
+bun arckode make:connector nombre-x mod1 mod2  # conectar dos módulos (kebab-case)
+bun test                                 # correr todos los tests
+\`\`\`
+
+---
+
+## Notas para la IA
+
+- Si el módulo es CRUD simple: NO crees \`repository.ts\` ni \`usecases/\`. Pasás \`OrmRepository<T>\` directo al service.
+- Si el módulo tiene 3+ tablas: definí TODOS los modelos en \`model.ts\` y registralos en \`registerXxxModels(orm)\` (helper único). El \`index.ts\` queda limpio.
+- Si necesitás atomicidad: inyectá \`Transactor\` al service, no el ORM. Mantiene la dependency inversion.
+- Si el analyzer muestra \`LEGACY_ACTIONS_FOLDER\`, \`DUPLICATE_CONNECTOR\` o \`UNREGISTERED_CONNECTOR\`: arreglarlos ANTES de pushear código nuevo.
+`
+}

package/cli/stubs/module-stub.ts

@@ -18,8 +18,9 @@ export function indexStub(p: ModuleStubParams): string {
 // ⚠ REGLA: Append-only. No sacar ni modificar exports existentes.
 
 import { createModule, OrmRepository } from 'arckode-framework'
-import { ${p.name}Service } from './actions/service'
-import { ${p.name}Controller } from './actions/controller'
+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 }
@@ -45,6 +46,9 @@ export function ${p.name}Module() {
     },
 
     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)
@@ -65,10 +69,10 @@ export function ${p.name}Module() {
 `
 }
 
-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')
-
+// ─── model.ts — Definición de DB (schema) ───
+// Separado de types.ts porque conceptualmente describe la PERSISTENCIA (la DB),
+// no el contrato de TypeScript (DTOs). Cambia con migraciones, no con la API.
+export function modelStub(p: ModuleStubParams): string {
   const modelFields = p.fields
     .filter(f => !['id', 'createdAt', 'updatedAt', 'deletedAt'].includes(f.name))
     .map(f => {
@@ -80,13 +84,14 @@ export function typesStub(p: ModuleStubParams): string {
     })
     .join(',\n')
 
-  return `// ${p.module}/types.ts — DTOs y definición del modelo
-// Responsabilidad ÚNICA: definir la forma de los datos.
-// El módulo es dueño de su ModelDefinition — composition-root la importa desde aquí.
+  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 } from 'arckode-framework'
+import type { ModelDefinition, ORM } from 'arckode-framework'
 
-// Definición del modelo para ORM.define() — importar en composition-root.ts
 export const ${p.name}Model: ModelDefinition = {
   table: '${p.module}',
   fields: {
@@ -96,6 +101,22 @@ ${modelFields}
 ${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}
@@ -154,18 +175,21 @@ export interface ${p.name}Sockets {
 export function serviceStub(p: ModuleStubParams): string {
   const hasSearch = p.fields.some(f => f.type === 'string')
 
-  return `// ${p.module}/actions/service.ts — Lógica de negocio
+  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'
+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 = {}
@@ -209,6 +233,8 @@ export class ${p.name}Service {
     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
   }
 
@@ -241,14 +267,15 @@ export class ${p.name}Service {
 }
 
 export function controllerStub(p: ModuleStubParams): string {
-  return `// ${p.module}/actions/controller.ts — Capa HTTP
-// Responsabilidad ÚNICA: traducir request/response.
-// SIN lógica de negocio. SIN validación directa.
+  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'
+import { Create${p.name}Schema, Update${p.name}Schema } from './validators/schema'
 
 export class ${p.name}Controller {
   constructor(
@@ -301,7 +328,7 @@ export function validatorStub(p: ModuleStubParams): string {
       parts.push(' }')
       return parts.join('')
     })
-    .join('\n')
+    .join(',\n')
 
   const updateRules = p.fields
     .filter(f => f.name !== 'id' && f.name !== 'createdAt')
@@ -311,7 +338,7 @@ export function validatorStub(p: ModuleStubParams): string {
       parts.push(' }')
       return parts.join('')
     })
-    .join('\n')
+    .join(',\n')
 
   return `// ${p.module}/validators/schema.ts — Validación de entrada
 // Schemas planos, sin dependencias externas.
@@ -341,7 +368,7 @@ export function testStub(p: ModuleStubParams): string {
 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 '../actions/service'
+import { ${p.name}Service } from '../service'
 import type { ${p.name}DTO } from '../types'
 
 // silentLogger es una factory function — SIEMPRE llamarla con ()
@@ -469,6 +496,48 @@ ${sampleData.replace(`'${p.name} de ejemplo'`, `'${p.name} de ejemplo 2'`).repla
 `
 }
 
+// ─── repository.ts — OPCIONAL ────────────────────────────
+// NO se genera por default. Crealo a mano cuando:
+//   1. El service repite los mismos filtros en varios métodos
+//      (ej: findOne({ user_id, currency }) en 4 lugares)
+//   2. Necesitás queries con JOIN, IN, LIKE — el ORM builtin no las soporta
+//   3. Querés expresar la query en lenguaje del DOMINIO
+//      (ej: findActiveByUser vs findMany({ user_id, status: 'active' }))
+//
+// Si solo hacés CRUD pelado → NO necesitás repository.ts.
+// Pasás el OrmRepository<T> directo al service.
+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 })
+  // }
+}
+`
+}
+
 function mapTS(type: string): string {
   const map: Record<string, string> = { string: 'string', number: 'number', boolean: 'boolean', date: 'string' }
   return map[type] ?? 'unknown'

package/kernel/framework.ts

@@ -463,6 +463,35 @@ export interface RepositoryAdapter<T extends object = Record<string, unknown>> {
   ): Promise<PageResult<T>>
 }
 
+// ── Transactor — atomicidad cross-modelo SIN exponer ORM al service ──
+//
+// Los services NO reciben ORM. Para operaciones atómicas multi-tabla
+// (ledger doble entrada, transferencias, etc.), reciben Transactor.
+//
+// El service obtiene repos transaccionales por modelo dentro del run():
+//
+//   await this.transactor.run(async (repos) => {
+//     const walletRepo = repos.for<WalletDTO>('Wallet')
+//     const txRepo     = repos.for<TransactionDTO>('Transaction')
+//     await walletRepo.update(id, { balance })
+//     await txRepo.create({ ... })
+//   })
+//
+// Si una operación dentro de run() falla, todo se rolleabackea automáticamente.
+//
+// Implementaciones:
+//   OrmTransactor → built-in, delega a ORM.transaction()
+//   Custom        → implementar para Prisma, Drizzle, MongoDB, etc.
+
+export interface TransactionalRepos {
+  /** Crea un RepositoryAdapter<T> ligado a la transacción activa para el modelo dado. */
+  for<T extends object = Record<string, unknown>>(modelName: string): RepositoryAdapter<T>
+}
+
+export interface Transactor {
+  run<R>(fn: (repos: TransactionalRepos) => Promise<R>): Promise<R>
+}
+
 // ── ORM — SOLID: S = solo ORM, D = depende de DbAdapter ──
 export class ORM {
   private models = new Map<string, ModelDefinition>()
@@ -518,11 +547,28 @@ export class ORM {
 
   private deserializeFromDb(def: ModelDefinition, row: ModelResult): ModelResult {
     const result = { ...row } as Record<string, unknown>
+
+    // Deserializar campos JSON almacenados como string
     for (const [k, field] of Object.entries(def.fields)) {
       if (field.type === 'json' && typeof result[k] === 'string') {
         try { result[k] = JSON.parse(result[k] as string) } catch { /* no es JSON válido */ }
       }
     }
+
+    // Normalizar timestamps que PostgreSQL devuelve en minúscula
+    // PostgreSQL baja el case de identificadores no-quoted: createdAt → createdat
+    const tsMap: Record<string, string> = {
+      createdat:  'createdAt',
+      updatedat:  'updatedAt',
+      deletedat:  'deletedAt',
+    }
+    for (const [lower, camel] of Object.entries(tsMap)) {
+      if (lower in result && !(camel in result)) {
+        result[camel] = result[lower]
+        delete result[lower]
+      }
+    }
+
     return result as ModelResult
   }
 
@@ -973,6 +1019,31 @@ export class OrmRepository<T extends object = Record<string, unknown>>
   }
 }
 
+// ── OrmTransactor — implementación SQL del Transactor ──
+//
+// Composition root:
+//   const transactor = new OrmTransactor(orm)
+//   const service = new WalletsService(walletRepo, txRepo, transactor, logger, cache)
+//
+// El service recibe Transactor (interfaz). Para swapear a Prisma:
+//   class PrismaTransactor implements Transactor { ... }
+//   const transactor = new PrismaTransactor(prisma)
+//   El service NO cambia.
+
+export class OrmTransactor implements Transactor {
+  constructor(private readonly orm: ORM) {}
+
+  run<R>(fn: (repos: TransactionalRepos) => Promise<R>): Promise<R> {
+    return this.orm.transaction(async (txOrm) => {
+      const repos: TransactionalRepos = {
+        for: <T extends object = Record<string, unknown>>(modelName: string) =>
+          new OrmRepository<T>(txOrm, modelName) as RepositoryAdapter<T>,
+      }
+      return fn(repos)
+    })
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════
 // 6. ROUTER + HTTP — Enrutamiento con middlewares y error handler
 // ═══════════════════════════════════════════════════════════════
@@ -1886,7 +1957,7 @@ export default {
   Logger, ConsoleTransport,
   ConfigStore, loadEnv,
   Container,
-  ORM, OrmRepository,
+  ORM, OrmRepository, OrmTransactor,
   Router, NodeServer,
   validateSchema,
   Auth, MemoryCache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.0.7",
+  "version": "1.1.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",
@@ -55,13 +55,12 @@
     "analyze:framework": "bun run cli/index.ts analyze"
   },
   "dependencies": {
-    "arckode-framework": "^1.0.3",
     "jsonwebtoken": "^9.0.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11.0.0",
     "mysql2": ">=3.0.0",
-    "pg": ">=8.0.0",
+    "pg": "^8.0.0",
     "redis": ">=4.0.0",
     "nodemailer": ">=6.0.0"
   },
@@ -88,6 +87,7 @@
     "@types/nodemailer": "^6.4.0",
     "@types/pg": "^8.11.0",
     "bun-types": "^1.3.14",
+    "pg": "^8.0.0",
     "typescript": "^5.6.0"
   },
   "keywords": [

package/skills/auth/SKILL.md

@@ -36,7 +36,7 @@ JWT_REFRESH_SECRET=otra-cadena-distinta-para-refresh-tokens
 ## 2. REGISTRO Y LOGIN (patrón completo)
 
 ```ts
-// En el módulo de autenticación — actions/service.ts
+// En el módulo de autenticación — service.ts (al root del módulo)
 export class AuthService {
   constructor(
     private repo: RepositoryAdapter<UserDTO>,

package/skills/cli/SKILL.md

@@ -28,20 +28,26 @@ arckode db:migrate --rollback          # Revertir última migración
 arckode make:module Producto
 ```
 
-Genera en `src/modules/producto/`:
+Genera en `src/modules/producto/` (nueva estructura):
 ```
-index.ts              ← ProductoModule() con createModule + OrmRepository + rutas
-types.ts              ← ProductoModel (ModelDefinition) + ProductoDTO + CreateProductoDTO
-sockets.ts            ← ProductosSockets interface + SocketsAware
-actions/
-  service.ts          ← ProductosService con RepositoryAdapter<ProductoDTO>
-  controller.ts       ← ProductosController con validateSchema en store/update
+index.ts              ← ProductoModule() — registra modelos, crea repos, wirea rutas
+model.ts              ← ProductoModel (ModelDefinition) + registerProductoModels(orm)
+types.ts              ← ProductoDTO + CreateProductoDTO + UpdateProductoDTO + queries
+sockets.ts            ← ProductosSockets interface
+service.ts            ← ProductosService con RepositoryAdapter<ProductoDTO>  (al root)
+controller.ts         ← ProductosController con validateSchema en store/update  (al root)
 validators/
   schema.ts           ← crearProductoSchema + actualizarProductoSchema
 tests/
   service.test.ts     ← 2 test cases: listar + crear con error
 ```
 
+**Opcionales (no generados — agregar a mano cuando aplique):**
+- `repository.ts` → queries con nombres del dominio (si el service repite filtros)
+- `usecases/{caso}.ts` → solo si hay 3+ flujos DIFERENTES (no CRUD)
+
+`service.ts` y `controller.ts` van al ROOT del módulo. `model.ts` está separado de `types.ts` por convención: schema DB vs contrato TypeScript.
+
 **Importante:** El nombre se usa en PascalCase para clases, camelCase para variables, kebab-case para rutas:
 - `arckode make:module LineaPedido` → clase `LineaPedidoService`, tabla `linea_pedidos`, ruta `/linea-pedidos`
 
@@ -102,11 +108,11 @@ Output ejemplo:
 ```
 🔍 Analizando proyecto...
 
-❌ DIRECT_MODULE_IMPORT         modules/pedidos/actions/service.ts:5
-   "import { ProductosService } from '../productos/actions/service'"
+❌ DIRECT_MODULE_IMPORT         modules/pedidos/service.ts:5
+   "import { ProductosService } from '../productos/service'"
    → Los módulos no pueden importar de otros módulos directamente.
 
-❌ CONTROLLER_MISSING_VALIDATION modules/productos/actions/controller.ts:23
+❌ CONTROLLER_MISSING_VALIDATION modules/productos/controller.ts:23
    "router.post sin validateSchema()"
    → Todo POST debe validar el body antes de llamar al service.
 
@@ -126,8 +132,11 @@ Resumen: 2 errores, 1 advertencia
 | Código | Severidad | Descripción |
 |--------|-----------|-------------|
 | `MISSING_INDEX` | ❌ | Módulo sin index.ts |
-| `MISSING_SERVICE` | ❌ | Sin actions/service.ts |
-| `MISSING_CONTROLLER` | ❌ | Sin actions/controller.ts |
+| `MISSING_SERVICE` | ❌ | Sin service.ts (al root del módulo) |
+| `MISSING_CONTROLLER` | ❌ | Sin controller.ts (al root del módulo) |
+| `LEGACY_ACTIONS_FOLDER` | ⚠️ | Módulo usa estructura legacy actions/ — mover al root |
+| `DUPLICATE_CONNECTOR` | ❌ | Conectores con mismo nombre lógico (kebab + camelCase) |
+| `UNREGISTERED_CONNECTOR` | ❌ | Archivo en connectors/ no importado en composition-root |
 | `MISSING_TYPES` | ❌ | Sin types.ts |
 | `MISSING_VALIDATORS` | ❌ | Sin validators/schema.ts |
 | `MISSING_TESTS` | ❌ | Sin directorio tests/ |

package/skills/connectors/SKILL.md

@@ -60,8 +60,8 @@ export interface PedidosSockets {
   onPedidoCancelado?:  (pedido: PedidoDTO) => Promise<void>
 }
 
-// En actions/service.ts
-import type { PedidosSockets } from '../sockets'
+// En service.ts (al root del módulo)
+import type { PedidosSockets } from './sockets'
 
 export class PedidosService {
   private sockets: PedidosSockets = {}
@@ -184,8 +184,8 @@ events.on('pedido.confirmado', async (event) => {
 ## 8. ANTI-PATRONES DE CONECTORES
 
 ```ts
-// ❌ Importar desde actions/service directamente (viola REGLA #1)
-import { PedidosService } from '../modules/pedidos/actions/service'  // NO
+// ❌ Importar desde ./service directamente (viola REGLA #1)
+import { PedidosService } from '../modules/pedidos/service'  // NO
 
 // ✅ Solo desde index.ts (puerta pública)
 import type { PedidosService } from '../modules/pedidos'

package/skills/helpers/SKILL.md

@@ -63,7 +63,7 @@ class PedidosService {
 | Tipo | Dónde va | Ejemplo |
 |------|---------|---------|
 | Función pura de transformación | `shared/helpers/` | `formatearFecha`, `slugify`, `calcularIVA` |
-| Lógica de negocio | `modules/{modulo}/actions/service.ts` | `calcularDescuento(pedido)` |
+| Lógica de negocio | `modules/{modulo}/service.ts` | `calcularDescuento(pedido)` |
 | Validación de dominio | `modules/{modulo}/validators/schema.ts` | Schema de validación |
 | Constante compartida | `shared/constants.ts` | `IVA_RATE = 0.18` |
 | Tipo/interfaz compartida | `shared/types.ts` | `Paginado<T>`, `ApiResponse<T>` |