arckode-framework 1.0.8 → 1.1.0

package/cli/analyze.ts

@@ -42,12 +42,15 @@ export interface Violation {
     | 'IDOR_RISK'                      // findById sin assertOwnership posterior
     // ── Portabilidad ──
     | 'SERVICE_DEPENDS_ON_ORM'         // service inyecta ORM en lugar de RepositoryAdapter
+    // ── Conectores ──
+    | 'DUPLICATE_CONNECTOR'            // mismo nombre lógico con distinto casing (foo-bar.ts y fooBar.ts)
+    | 'UNREGISTERED_CONNECTOR'         // archivo existe pero no está en composition-root.ts
   module: string
   message: string
 }
 
 export interface Warning {
-  type: 'NO_CONNECTORS' | 'SINGLE_MODULE' | 'NO_COMPOSITION_ROOT' | 'INDEX_PENDING_CHANGES'
+  type: 'NO_CONNECTORS' | 'SINGLE_MODULE' | 'NO_COMPOSITION_ROOT' | 'INDEX_PENDING_CHANGES' | 'LEGACY_ACTIONS_FOLDER'
   message: string
 }
 
@@ -55,6 +58,8 @@ export async function analyzeProject(basePath: string): Promise<AnalysisResult>
   const violations: Violation[] = []
   const warnings: Warning[] = []
   const modules: ModuleReport[] = []
+  // Mapa de paths internos resueltos por módulo (nueva estructura o legacy)
+  const internalPaths = new Map<string, { service: string | null; controller: string | null }>()
 
   const srcPath = join(basePath, 'src')
   const modulesPath = join(srcPath, 'modules')
@@ -80,21 +85,28 @@ export async function analyzeProject(basePath: string): Promise<AnalysisResult>
 
     for (const name of moduleNames) {
       const modPath = join(modulesPath, name)
+      // Soporta estructura nueva (root) y legacy (actions/) — el path resuelto
+      // queda guardado en internalPaths para reusar en chequeos posteriores
+      const servicePath = await resolvePath(modPath, ['service.ts', 'actions/service.ts'])
+      const controllerPath = await resolvePath(modPath, ['controller.ts', 'actions/controller.ts'])
+
       const report: ModuleReport = {
         name,
         hasIndex: await fileExists(join(modPath, 'index.ts')),
-        hasService: await fileExists(join(modPath, 'actions', 'service.ts')),
-        hasController: await fileExists(join(modPath, 'actions', 'controller.ts')),
+        hasService: servicePath !== null,
+        hasController: controllerPath !== null,
         hasTypes: await fileExists(join(modPath, 'types.ts')),
         hasSockets: await fileExists(join(modPath, 'sockets.ts')),
         hasValidators: await fileExists(join(modPath, 'validators', 'schema.ts')),
         hasTests: await fileExists(join(modPath, 'tests', 'service.test.ts')),
       }
 
+      internalPaths.set(name, { service: servicePath, controller: controllerPath })
+
       if (!report.hasIndex) violations.push({ type: 'MISSING_INDEX', module: name, message: `Módulo "${name}" sin index.ts (puerta pública)` })
       if (!report.hasTypes) violations.push({ type: 'MISSING_TYPES', module: name, message: `Módulo "${name}" sin types.ts (DTOs)` })
       if (!report.hasSockets) violations.push({ type: 'MISSING_SOCKETS', module: name, message: `Módulo "${name}" sin sockets.ts (hooks opcionales)` })
-      if (!report.hasService) violations.push({ type: 'MISSING_SERVICE', module: name, message: `Módulo "${name}" sin actions/service.ts` })
+      if (!report.hasService) violations.push({ type: 'MISSING_SERVICE', module: name, message: `Módulo "${name}" sin service.ts (al root del módulo)` })
       if (!report.hasValidators) violations.push({ type: 'MISSING_VALIDATORS', module: name, message: `Módulo "${name}" sin validators/schema.ts` })
       if (!report.hasTests) violations.push({ type: 'MISSING_TESTS', module: name, message: `Módulo "${name}" sin tests/` })
 
@@ -115,6 +127,41 @@ export async function analyzeProject(basePath: string): Promise<AnalysisResult>
     if (connectors.length === 0 && modules.length > 1) {
       warnings.push({ type: 'NO_CONNECTORS', message: `Hay ${modules.length} módulos pero 0 conectores. Los módulos no están conectados.` })
     }
+
+    // Detectar conectores duplicados (ej: trading-wallets.ts + tradingWallets.ts)
+    const canonicalMap = new Map<string, string[]>()
+    for (const file of connectors) {
+      const canonical = canonicalizeConnectorName(file)
+      const list = canonicalMap.get(canonical) ?? []
+      list.push(file)
+      canonicalMap.set(canonical, list)
+    }
+    for (const [canonical, files] of canonicalMap) {
+      if (files.length > 1) {
+        violations.push({
+          type: 'DUPLICATE_CONNECTOR',
+          module: 'connectors',
+          message: `Conectores duplicados con mismo nombre lógico "${canonical}": ${files.join(', ')}. Eliminar los stubs muertos del CLI.`,
+        })
+      }
+    }
+
+    // Detectar conectores no registrados en composition-root.ts
+    try {
+      const crContent = await readFile(crPath, 'utf-8')
+      for (const file of connectors) {
+        const basename = file.replace(/\.ts$/, '')
+        // El conector debe aparecer como import o como string literal en addConnector()
+        const importPattern = new RegExp(`from\\s+['"][^'"]*connectors\\/${basename}['"]`)
+        if (!importPattern.test(crContent)) {
+          violations.push({
+            type: 'UNREGISTERED_CONNECTOR',
+            module: 'connectors',
+            message: `Conector "${file}" existe pero no se importa en composition-root.ts. Dead code o falta registrar con system.addConnector().`,
+          })
+        }
+      }
+    } catch { /* sin composition-root, ya warned arriba */ }
   } catch {
     // No hay carpeta de conectores, puede ser válido si hay 1 módulo
   }
@@ -227,36 +274,52 @@ export async function analyzeProject(basePath: string): Promise<AnalysisResult>
       }
     } catch { /* no test file — ya detectado por MISSING_TESTS */ }
 
+    // Paths resueltos (nueva estructura o legacy)
+    const paths = internalPaths.get(module.name) ?? { service: null, controller: null }
+    const controllerPath = paths.controller
+    const servicePath = paths.service
+
     // 3. VALIDACIONES INCOMPLETAS — controller con POST/PUT/PATCH sin validateSchema
-    const controllerPath = join(modPath, 'actions', 'controller.ts')
-    try {
-      const ctrlContent = await readFile(controllerPath, 'utf-8')
-      const hasMutatingRoute = /router\.(post|put|patch)\s*\(/.test(ctrlContent)
-      const hasValidation = /validateSchema\s*\(/.test(ctrlContent)
-      if (hasMutatingRoute && !hasValidation) {
-        violations.push({
-          type: 'CONTROLLER_MISSING_VALIDATION',
-          module: module.name,
-          message: `"${module.name}/controller.ts" tiene rutas POST/PUT/PATCH sin validateSchema(). Datos no validados llegan al service.`,
-        })
-      }
-    } catch { /* no controller */ }
+    if (controllerPath) {
+      try {
+        const ctrlContent = await readFile(controllerPath, 'utf-8')
+        const hasMutatingRoute = /router\.(post|put|patch)\s*\(/.test(ctrlContent)
+        const hasValidation = /validateSchema\s*\(/.test(ctrlContent)
+        if (hasMutatingRoute && !hasValidation) {
+          violations.push({
+            type: 'CONTROLLER_MISSING_VALIDATION',
+            module: module.name,
+            message: `"${module.name}/controller.ts" tiene rutas POST/PUT/PATCH sin validateSchema(). Datos no validados llegan al service.`,
+          })
+        }
+      } catch { /* no controller */ }
 
-    // 4. LÓGICA EN CONTROLLER — ORM directo en controller (debería estar en service)
-    try {
-      const ctrlContent = await readFile(controllerPath, 'utf-8')
-      const ormInController = /\borm\.(findMany|findById|create|update|delete|paginate|count)\s*\(/.test(ctrlContent)
-      if (ormInController) {
-        violations.push({
-          type: 'BUSINESS_LOGIC_IN_CONTROLLER',
-          module: module.name,
-          message: `"${module.name}/controller.ts" llama al ORM directamente. La lógica de datos va en service.ts.`,
-        })
-      }
-    } catch { /* no controller */ }
+      // 4. LÓGICA EN CONTROLLER — ORM directo en controller (debería estar en service)
+      try {
+        const ctrlContent = await readFile(controllerPath, 'utf-8')
+        const ormInController = /\borm\.(findMany|findById|create|update|delete|paginate|count)\s*\(/.test(ctrlContent)
+        if (ormInController) {
+          violations.push({
+            type: 'BUSINESS_LOGIC_IN_CONTROLLER',
+            module: module.name,
+            message: `"${module.name}/controller.ts" llama al ORM directamente. La lógica de datos va en service.ts.`,
+          })
+        }
+      } catch { /* no controller */ }
+    }
+
+    // Warning: legacy folder layout
+    if ((servicePath && servicePath.includes('/actions/')) || (controllerPath && controllerPath.includes('/actions/'))) {
+      warnings.push({
+        type: 'LEGACY_ACTIONS_FOLDER',
+        message: `"${module.name}" usa la estructura legacy actions/. Mover service.ts y controller.ts al root del módulo.`,
+      })
+    }
 
     // 5. GOD SERVICE — service con más de 200 líneas indica demasiadas responsabilidades
-    const servicePath = join(modPath, 'actions', 'service.ts')
+    if (!servicePath) continue  // sin service, skip los siguientes checks
+    // El service principal puede tener orquestador < 200 líneas + sub-services en usecases/
+    // Aquí solo medimos el archivo service.ts principal
     try {
       const serviceContent = await readFile(servicePath, 'utf-8')
       const lineCount = serviceContent.split('\n').length
@@ -264,7 +327,7 @@ export async function analyzeProject(basePath: string): Promise<AnalysisResult>
         violations.push({
           type: 'GOD_SERVICE',
           module: module.name,
-          message: `"${module.name}/service.ts" tiene ${lineCount} líneas. Un service > 200 líneas es un God Object — dividir en servicios especializados.`,
+          message: `"${module.name}/service.ts" tiene ${lineCount} líneas. Un service > 200 líneas es un God Object — extraer a usecases/.`,
         })
       }
     } catch { /* no service */ }
@@ -311,24 +374,55 @@ export async function analyzeProject(basePath: string): Promise<AnalysisResult>
     } catch { /* no service */ }
 
     // 8. IDOR RISK — findById sin assertOwnership inmediatamente después
-    try {
-      const serviceContent = await readFile(servicePath, 'utf-8')
-      const lines = serviceContent.split('\n')
-      for (let i = 0; i < lines.length; i++) {
-        if (/\bfindById\s*\(/.test(lines[i] ?? '')) {
-          // Buscar assertOwnership en las siguientes 5 líneas
-          const window = lines.slice(i + 1, i + 6).join('\n')
-          if (!window.includes('assertOwnership') && !window.includes('userId') && !window.includes('ownerId')) {
-            violations.push({
-              type: 'IDOR_RISK',
-              module: module.name,
-              message: `"${module.name}/service.ts" línea ${i + 1}: findById sin verificación de ownership. Usar auth.assertOwnership() para prevenir IDOR.`,
-            })
-            break
+    // Analiza también sub-services en usecases/ (la nueva estructura) o actions/ (legacy)
+    const filesToScan: string[] = [servicePath]
+    for (const subdir of ['usecases', 'actions']) {
+      const subdirPath = join(modPath, subdir)
+      try {
+        const subEntries = await readdir(subdirPath, { withFileTypes: true })
+        for (const e of subEntries) {
+          if (e.isFile() && e.name.endsWith('.ts') && e.name !== 'service.ts' && e.name !== 'controller.ts') {
+            filesToScan.push(join(subdirPath, e.name))
           }
         }
-      }
-    } catch { /* no service */ }
+      } catch { /* sin subdir */ }
+    }
+
+    for (const filePath of filesToScan) {
+      // Skip archivos de adapter/repo/interfaz — declaran findById pero no es business logic
+      if (/-orm\.ts$|-repo\.ts$|-repository\.ts$|repository\.ts$/.test(filePath)) continue
+      try {
+        const serviceContent = await readFile(filePath, 'utf-8')
+        const lines = serviceContent.split('\n')
+        let insideInterface = 0
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i] ?? ''
+          // Trackear si estamos dentro de un bloque de interface
+          if (/^\s*(export\s+)?interface\s+\w+/.test(line)) insideInterface++
+          const opens = (line.match(/\{/g) ?? []).length
+          const closes = (line.match(/\}/g) ?? []).length
+          if (insideInterface > 0) insideInterface = Math.max(0, insideInterface + opens - closes)
+
+          // Skip findById en interfaces TS — no es business logic
+          if (insideInterface > 0) continue
+          // Skip declaraciones de tipo: "findById(...): Promise<...>" sin await ni asignación
+          if (/^\s*findById\s*\([^)]*\)\s*:/.test(line)) continue
+
+          if (/\bfindById\s*\(/.test(line)) {
+            const window = lines.slice(i + 1, i + 6).join('\n')
+            if (!window.includes('assertOwnership') && !window.includes('userId') && !window.includes('ownerId')) {
+              const relFile = relative(modulesPath, filePath)
+              violations.push({
+                type: 'IDOR_RISK',
+                module: module.name,
+                message: `"${relFile}" línea ${i + 1}: findById sin verificación de ownership. Usar auth.assertOwnership() para prevenir IDOR.`,
+              })
+              break
+            }
+          }
+        }
+      } catch { /* file unreadable */ }
+    }
 
     // 9. SERVICE DEPENDS ON ORM — service inyecta ORM en lugar de RepositoryAdapter (Regla #18)
     try {
@@ -357,6 +451,25 @@ async function fileExists(path: string): Promise<boolean> {
   try { await access(path); return true } catch { return false }
 }
 
+// Resuelve el primer path existente de una lista de candidatos relativos.
+// Permite soportar la estructura nueva (root del módulo) y la legacy (actions/).
+async function resolvePath(modPath: string, candidates: string[]): Promise<string | null> {
+  for (const candidate of candidates) {
+    const full = join(modPath, candidate)
+    if (await fileExists(full)) return full
+  }
+  return null
+}
+
+// Normaliza nombre de conector a forma canónica para detectar duplicados
+// "trading-wallets.ts" y "tradingWallets.ts" → "tradingwallets"
+function canonicalizeConnectorName(filename: string): string {
+  return filename
+    .replace(/\.ts$/, '')
+    .replace(/[-_]/g, '')
+    .toLowerCase()
+}
+
 async function getAllTsFiles(dir: string): Promise<string[]> {
   const files: string[] = []
   try {
@@ -424,6 +537,8 @@ export function printAnalysis(result: AnalysisResult): void {
         byCategory['Performance']!.push(v)
       } else if (['SERVICE_DEPENDS_ON_ORM'].includes(v.type)) {
         byCategory['Portabilidad']!.push(v)
+      } else if (['DUPLICATE_CONNECTOR', 'UNREGISTERED_CONNECTOR'].includes(v.type)) {
+        byCategory['Acoplamiento']!.push(v)
       } else {
         byCategory['Calidad']!.push(v)
       }

package/cli/generate.ts

@@ -5,7 +5,7 @@ import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { ModuleStubParams } from './stubs/module-stub'
 import {
-  indexStub, typesStub, socketsStub,
+  indexStub, modelStub, typesStub, socketsStub,
   serviceStub, controllerStub, validatorStub,
   testStub, migrationStub, seedStub,
 } from './stubs/module-stub'
@@ -52,15 +52,20 @@ export async function generateModule(params: {
   }
 
   const modulePath = join(basePath, 'modules', kebab)
-  await mkdir(join(modulePath, 'actions'), { recursive: true })
   await mkdir(join(modulePath, 'validators'), { recursive: true })
   await mkdir(join(modulePath, 'tests'), { recursive: true })
 
+  // Nueva estructura:
+  //   - service.ts y controller.ts al ROOT del módulo
+  //   - model.ts separado de types.ts (schema DB vs DTOs)
+  //   - repository.ts NO se genera por default (es opcional)
+  //   - usecases/ se crea solo si el service supera 200 líneas (extracción manual)
   await writeFile(join(modulePath, 'index.ts'), indexStub(stubParams), 'utf-8')
+  await writeFile(join(modulePath, 'model.ts'), modelStub(stubParams), 'utf-8')
   await writeFile(join(modulePath, 'types.ts'), typesStub(stubParams), 'utf-8')
   await writeFile(join(modulePath, 'sockets.ts'), socketsStub(stubParams), 'utf-8')
-  await writeFile(join(modulePath, 'actions/service.ts'), serviceStub(stubParams), 'utf-8')
-  await writeFile(join(modulePath, 'actions/controller.ts'), controllerStub(stubParams), 'utf-8')
+  await writeFile(join(modulePath, 'service.ts'), serviceStub(stubParams), 'utf-8')
+  await writeFile(join(modulePath, 'controller.ts'), controllerStub(stubParams), 'utf-8')
   await writeFile(join(modulePath, 'validators/schema.ts'), validatorStub(stubParams), 'utf-8')
   await writeFile(join(modulePath, 'tests/service.test.ts'), testStub(stubParams), 'utf-8')
 
@@ -75,20 +80,20 @@ export async function generateModule(params: {
   await writeFile(join(seedsPath, `${kebab}.ts`), seedStub(stubParams), 'utf-8')
 
   console.log(`✅ Módulo "${pascal}" creado en modules/${kebab}`)
-  console.log(`   Archivos: index, types, sockets, service, controller, validators, tests`)
+  console.log(`   Archivos: index, model, types, sockets, service, controller, validators, tests`)
+  console.log(`   Opcional: crear repository.ts si necesitás queries del dominio`)
   console.log(`   Migración: migrations/..._create_${kebab}.ts`)
   console.log(`   Seed: seeds/${kebab}.ts`)
   console.log('')
   console.log(`   Registralo en composition-root.ts:`)
   console.log(`   import { ${pascal}Module } from './modules/${kebab}'`)
-  console.log(`   import { OrmRepository } from 'arckode-framework'`)
-  console.log(`   import type { ${pascal}DTO } from './modules/${kebab}/types'`)
-  console.log(`   orm.define('${pascal}', { table: '${kebab}', fields: { nombre: { type: 'string' } }, timestamps: true })`)
-  console.log(`   const ${kebab}Repo = new OrmRepository<${pascal}DTO>(orm, '${pascal}')`)
-  console.log(`   system.addModule(${pascal}Module)   // pasar ${kebab}Repo al módulo`)
+  console.log(`   system.addModule(${pascal}Module())`)
+  console.log(`   // El módulo registra su modelo internamente via register${pascal}Models(orm)`)
 }
 
 // ─── Generador de conector ───
+// Archivo: kebab-case (consistente con composition-root.ts)
+// Función exportada: connect + PascalCase
 export async function generateConnector(params: {
   name: string
   basePath: string
@@ -96,34 +101,36 @@ export async function generateConnector(params: {
   description?: string
 }): Promise<void> {
   const { name, basePath, modules, description = '' } = params
-  const camel = toCase(name, 'camel')
+  const kebab = toCase(name, 'kebab')
+  const pascal = toCase(name, 'pascal')
+  const fnName = `connect${pascal}`
 
   const connectorPath = join(basePath, 'connectors')
   await mkdir(connectorPath, { recursive: true })
 
-  await writeFile(join(connectorPath, `${camel}.ts`), [
-    `// connectors/${camel}.ts — Conector entre módulos`,
-    `// Responsabilidad ÚNICA: conectar módulos SIN modificarlos`,
-    `// SOLID: cada conector conecta módulos, no contiene lógica de negocio`,
+  await writeFile(join(connectorPath, `${kebab}.ts`), [
+    `// connectors/${kebab}.ts — Conector entre módulos`,
+    `// Responsabilidad ÚNICA: wirear módulos vía setSockets()`,
+    `// REGLA #3: cero lógica de negocio. Solo DELEGAR a acciones públicas.`,
     ``,
     `// Conecta: ${modules.join(' → ')}`,
     description ? `// Descripción: ${description}` : '',
     ``,
     `import type { ConnectorContext } from 'arckode-framework'`,
+    modules.map(m => `import type { ${toCase(m, 'pascal')}Service } from '../modules/${toCase(m, 'kebab')}'`).join('\n'),
     ``,
-    `export function ${camel}(ctx: ConnectorContext): void {`,
-    modules.map(m => `  const ${toCase(m, 'camel')} = ctx.resolveModule<any>('${m}')`).join('\n'),
+    `export function ${fnName}(ctx: ConnectorContext): void {`,
+    modules.map(m => `  const ${toCase(m, 'camel')} = ctx.resolveModule<${toCase(m, 'pascal')}Service>('${toCase(m, 'kebab')}')`).join('\n'),
     ``,
-    modules.slice(1).map(m => {
-      const prev = toCase(modules[0] ?? '', 'camel')
-      const curr = toCase(m, 'camel')
-      return `  // ${prev} → ${curr}: conectar eventos`
-    }).join('\n'),
+    `  // Ejemplo: ${toCase(modules[0] ?? '', 'camel')}.setSockets({ onEvent: async (payload) => { await ${toCase(modules[1] ?? '', 'camel')}.action(payload) } })`,
     `}`,
     ``,
   ].join('\n'))
 
-  console.log(`✅ Conector "${camel}" creado en ${connectorPath} (conecta: ${modules.join(', ')})`)
+  console.log(`✅ Conector "${kebab}.ts" creado (función: ${fnName})`)
+  console.log(`   Registralo en composition-root.ts:`)
+  console.log(`   import { ${fnName} } from './connectors/${kebab}'`)
+  console.log(`   system.addConnector('${kebab}', ${fnName})`)
 }
 
 function mapFieldType(type: string): string {

package/cli/index.ts

@@ -6,6 +6,7 @@ import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { generateModule, generateConnector } from './generate'
 import { analyzeProject, printAnalysis, buildManifest } from './analyze'
+import { claudeMdStub } from './stubs/claude-md-stub'
 
 async function main() {
   const [, , cmd, ...args] = process.argv
@@ -18,7 +19,8 @@ async function main() {
 
       // Detectar DB adapter: --db=mysql | --db=postgres | default: sqlite
       const dbFlag = args.find(a => a.startsWith('--db='))?.split('=')[1] ?? 'sqlite'
-      const db = ['sqlite', 'mysql', 'postgres'].includes(dbFlag) ? dbFlag : 'sqlite'
+      const db: 'sqlite' | 'mysql' | 'postgres' =
+        dbFlag === 'mysql' || dbFlag === 'postgres' ? dbFlag : 'sqlite'
 
       const base = join(process.cwd(), name)
 
@@ -27,79 +29,9 @@ async function main() {
       await mkdir(join(base, 'src', 'connectors'), { recursive: true })
 
       // ─── CLAUDE.md ─────────────────────────────────────────────────────
-      await writeFile(join(base, 'CLAUDE.md'), [
-        `# CLAUDE.md — ${name}`,
-        `## Lee esto ANTES de escribir cualquier línea de código.`,
-        ``,
-        `### PASO 0 — Cargar contexto del sistema`,
-        `1. Leer \`arckode.json\` → saber qué módulos, rutas y modelos ya existen.`,
-        `2. Si no existe: \`bun run analyze --json\` para generarlo.`,
-        `3. Leer \`src/composition-root.ts\` → es la única fuente de verdad del sistema.`,
-        ``,
-        `### Reglas INMUTABLES (no se negocian, no se omiten)`,
-        ``,
-        `| # | Regla | Detectada por |`,
-        `|---|-------|--------------|`,
-        `| 1 | Módulos NO importan de otros módulos → usar conectores | \`arckode analyze\` |`,
-        `| 2 | index.ts es APPEND-ONLY → no eliminar exports | 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 | Service > 200 líneas → dividir | \`arckode analyze\` |`,
-        `| 9 | findById → verificar ownership inmediatamente (IDOR) | \`arckode analyze\` |`,
-        `| 10 | ORM dentro de un loop → N+1 garantizado, prohibido | \`arckode analyze\` |`,
-        `| 11 | Service recibe RepositoryAdapter<T>, no ORM directo | \`arckode analyze\` |`,
-        ``,
-        `### 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`,
-        `  ¿Modifico index.ts? → Solo append`,
-        `  ¿Pongo lógica en el conector? → NO`,
-        `  ¿Comparto una tabla? → NO`,
-        ``,
-        `PASO 3 — GENERAR`,
-        `  Estructura obligatoria: index.ts, types.ts, sockets.ts,`,
-        `  actions/service.ts, actions/controller.ts,`,
-        `  validators/schema.ts, tests/service.test.ts`,
-        ``,
-        `PASO 4 — VERIFICAR`,
-        `  bun run analyze --json → violations: 0`,
-        `  bun test → 0 fallos`,
-        `\`\`\``,
-        ``,
-        `### DB Adapter activo: \`${db}\``,
-        ``,
-        `### Estructura del proyecto`,
-        `\`\`\``,
-        `src/`,
-        `  composition-root.ts    ← TODO el sistema`,
-        `  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 de BD`,
-        `\`\`\``,
-        ``,
-        `### 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 mod1 mod2   # conectar dos módulos`,
-        `bun test                         # correr todos los tests`,
-        `\`\`\``,
-      ].join('\n'))
+      // Contenido del stub vive en cli/stubs/claude-md-stub.ts
+      // (sincronizado con CLAUDE.md maestro del framework)
+      await writeFile(join(base, 'CLAUDE.md'), claudeMdStub({ projectName: name, db }))
 
       // composition-root.ts
       await writeFile(join(base, 'src', 'composition-root.ts'), [
@@ -165,14 +97,7 @@ async function main() {
         `const cache = new MemoryCache()`,
         `const auth = new Auth(jwtTokenAdapter, config.get('JWT_SECRET'), logger)`,
         ``,
-        `// ─── 3. MODELOS (cada módulo es dueño de su ModelDefinition) ─`,
-        `// import { MiModuloModel } from './modules/mi-modulo/types'`,
-        `// orm.define('MiModulo', MiModuloModel)`,
-        ``,
-        `// ─── 4. MIGRAR ───────────────────────────────`,
-        `await orm.migrate()`,
-        ``,
-        `// ─── 5. REGISTRAR ────────────────────────────`,
+        `// ─── 3. CONTAINER ────────────────────────────`,
         `container.register('config', () => config)`,
         `container.register('logger', () => logger)`,
         `container.register('db', () => dbAdapter, () => dbAdapter.close())`,
@@ -180,32 +105,44 @@ async function main() {
         `container.register('cache', () => cache)`,
         `container.init()`,
         ``,
-        `// ─── 6. SISTEMA ───────────────────────────────`,
+        `// ─── 4. SISTEMA ───────────────────────────────`,
         `const system = new System({`,
         `  config, container, logger, orm, router, http, cache, auth,`,
         `})`,
         ``,
-        `// Registrar módulos — usar factory functions generadas por arckode make:module:`,
+        `// ─── 5. MÓDULOS ───────────────────────────────`,
+        `// Cada módulo se autorregistra: su index.ts llama registerXxxModels(orm)`,
+        `// en el create(). Acá SOLO addModule(). No tocar orm.define() manualmente.`,
+        ``,
         `// import { MiModuloModule } from './modules/mi-modulo'`,
         `// system.addModule(MiModuloModule())`,
         ``,
-        `// Conectar módulos:`,
-        `// system.addConnector('nombre', (ctx) => {`,
-        `//   const modA = ctx.resolveModule('mod-a')`,
-        `//   ctx.resolveModule('mod-b', { onEvento: async (data) => modA.accion(data) })`,
-        `// })`,
+        `// ─── 6. CONECTORES ────────────────────────────`,
+        `// Generar con: arckode make:connector nombre-x mod-a mod-b`,
+        `// import { connectModAModB } from './connectors/mod-a-mod-b'`,
+        `// system.addConnector('mod-a-mod-b', connectModAModB)`,
+        ``,
+        `// Para atomicidad multi-tabla (financieras, ledgers, transferencias):`,
+        `// import { OrmTransactor } from 'arckode-framework'`,
+        `// const transactor = new OrmTransactor(orm)`,
+        `// → inyectarlo al service que lo necesite (Regla #19)`,
         ``,
-        `// ─── 7. RUTAS ─────────────────────────────────`,
+        `// ─── 7. RUTAS BASE ────────────────────────────`,
         `router.get('/health', async () => ({`,
         `  status: 200, body: { status: 'ok', uptime: process.uptime() }`,
         `}))`,
         ``,
-        `// ─── 8. SEEDS (solo en desarrollo) ────────────`,
+        `// ─── 8. INIT + MIGRATE + START ────────────────`,
+        `// Orden CRÍTICO: init() ejecuta los create() de los módulos (registra modelos),`,
+        `// luego migrate() crea las tablas, luego start() levanta el HTTP.`,
+        `system.init()`,
+        `await orm.migrate()`,
+        ``,
+        `// ─── 9. SEEDS (solo en desarrollo) ────────────`,
         `if (env.RUN_SEEDS === 'true') {`,
         `  // await seeds.runAll()`,
         `}`,
         ``,
-        `// ─── 9. INICIAR ───────────────────────────────`,
         `await system.start()`,
         ``,
         `process.on('SIGINT', async () => { await system.stop(); process.exit(0) })`,