arckode-framework 1.0.0

package/cli/analyze.ts

@@ -0,0 +1,506 @@
+// cli/analyze.ts — Analizador estático de arquitectura
+// Lee el proyecto como grafo y detecta violaciones
+// SOLID: cada chequeo es una función con una responsabilidad
+
+import { readdir, readFile, access } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+export interface AnalysisResult {
+  valid: boolean
+  modules: ModuleReport[]
+  connectors: string[]
+  violations: Violation[]
+  warnings: Warning[]
+}
+
+export interface ModuleReport {
+  name: string
+  hasIndex: boolean
+  hasService: boolean
+  hasController: boolean
+  hasTypes: boolean
+  hasSockets: boolean
+  hasValidators: boolean
+  hasTests: boolean
+}
+
+export interface Violation {
+  type:
+    | 'DIRECT_MODULE_IMPORT'
+    | 'MISSING_INDEX' | 'MISSING_CONTRACT' | 'MISSING_SERVICE' | 'MISSING_TYPES'
+    | 'MISSING_SOCKETS' | 'MISSING_VALIDATORS' | 'MISSING_TESTS'
+    | 'MISSING_CONNECTORS' | 'CONNECTOR_BUSINESS_LOGIC' | 'INDEX_PENDING_CHANGES'
+    // ── Los 6 que las reglas base no cubrían ──
+    | 'CONTROLLER_MISSING_VALIDATION'  // ruta POST/PUT/PATCH sin validateSchema
+    | 'BUSINESS_LOGIC_IN_CONTROLLER'   // ORM directo en controller
+    | 'EMPTY_MODULE_DESCRIPTION'       // descripción vacía en módulo
+    | 'TESTS_WITHOUT_CASES'            // test file sin test()
+    | 'SERVICE_IMPORTS_OTHER_MODULE'   // service cruza módulo
+    | 'GOD_SERVICE'                    // service > 200 líneas
+    // ── Seguridad y performance ──
+    | 'N_PLUS_ONE_RISK'                // ORM llamado dentro de loop en service
+    | 'IDOR_RISK'                      // findById sin assertOwnership posterior
+    // ── Portabilidad ──
+    | 'SERVICE_DEPENDS_ON_ORM'         // service inyecta ORM en lugar de RepositoryAdapter
+  module: string
+  message: string
+}
+
+export interface Warning {
+  type: 'NO_CONNECTORS' | 'SINGLE_MODULE' | 'NO_COMPOSITION_ROOT' | 'INDEX_PENDING_CHANGES'
+  message: string
+}
+
+export async function analyzeProject(basePath: string): Promise<AnalysisResult> {
+  const violations: Violation[] = []
+  const warnings: Warning[] = []
+  const modules: ModuleReport[] = []
+
+  const srcPath = join(basePath, 'src')
+  const modulesPath = join(srcPath, 'modules')
+  const connectorsPath = join(srcPath, 'connectors')
+  const crPath = join(srcPath, 'composition-root.ts')
+
+  // Verificar composition root
+  try {
+    await access(crPath)
+  } catch {
+    warnings.push({ type: 'NO_COMPOSITION_ROOT', message: 'No hay composition-root.ts en src/' })
+    return { valid: false, modules: [], connectors: [], violations, warnings }
+  }
+
+  // Leer módulos
+  try {
+    const moduleDirs = await readdir(modulesPath, { withFileTypes: true })
+    const moduleNames = moduleDirs.filter(d => d.isDirectory()).map(d => d.name)
+
+    if (moduleNames.length === 0) {
+      warnings.push({ type: 'SINGLE_MODULE', message: 'No hay módulos en src/modules/' })
+    }
+
+    for (const name of moduleNames) {
+      const modPath = join(modulesPath, name)
+      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')),
+        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')),
+      }
+
+      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.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/` })
+
+      modules.push(report)
+    }
+  } catch {
+    violations.push({ type: 'MISSING_INDEX', module: 'modules', message: 'No existe src/modules/' })
+  }
+
+  // Verificar conectores
+  const connectors: string[] = []
+  try {
+    const connectorFiles = await readdir(connectorsPath)
+    for (const file of connectorFiles) {
+      if (file.endsWith('.ts')) connectors.push(file)
+    }
+
+    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.` })
+    }
+  } catch {
+    // No hay carpeta de conectores, puede ser válido si hay 1 módulo
+  }
+
+  // Verificar imports directos entre módulos (REGLAS CLAUDE #1)
+  for (const module of modules) {
+    try {
+      const allFiles = await getAllTsFiles(join(modulesPath, module.name))
+      for (const file of allFiles) {
+        const content = await readFile(file, 'utf-8')
+        const relPath = file.replace(modulesPath, '')
+        for (const other of modules) {
+          if (other.name === module.name) continue
+          const importPattern = new RegExp(`from ['"][^'"]*\\/modules\\/${other.name}([/'"]|\$)`)
+          if (importPattern.test(content)) {
+            violations.push({
+              type: 'DIRECT_MODULE_IMPORT',
+              module: module.name,
+              message: `"${relPath}" importa directo de "${other.name}". Usar conector. (CLAUDE #1)`,
+            })
+          }
+        }
+      }
+    } catch { /* no actions dir */ }
+  }
+
+  // Verificar lógica de negocio en conectores (REGLA CLAUDE #3)
+  for (const connFile of connectors) {
+    try {
+      const content = await readFile(join(connectorsPath, connFile), 'utf-8')
+      // Detectar patrones de lógica de negocio en conectores
+      const businessPatterns = [
+        /\bif\s*\(/g, /\bswitch\s*\(/g, /\bfor\s*\(/g, /\bwhile\s*\(/g,
+        /\btry\s*\{/g, /\bcatch\s*\(/g, /\bnew\s+\w+Action/g,
+        /\.create\(/g, /\.update\(/g, /\.delete\(/g,
+      ]
+
+      // Contar ocurrencias — 1 o 2 pueden ser normales, más indica lógica
+      let businessHits = 0
+      for (const pattern of businessPatterns) {
+        const matches = content.match(pattern)
+        if (matches) businessHits += matches.length
+      }
+
+      if (businessHits > 3) {
+        violations.push({
+          type: 'CONNECTOR_BUSINESS_LOGIC',
+          module: connFile,
+          message: `"${connFile}" tiene ${businessHits} patrones de lógica de negocio. Los conectores solo deben wirear. (CLAUDE #3)`,
+        })
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Verificar regla APPEND-ONLY (REGLA CLAUDE #2) — detecta exports removidos
+  // Busca comentarios de deprecación o conflicto en index.ts
+  for (const module of modules) {
+    const indexPath = join(modulesPath, module.name, 'index.ts')
+    try {
+      const content = await readFile(indexPath, 'utf-8')
+      // Si index.ts tiene comentarios TODO o FIXME sobre exports rotos
+      if (content.includes('TODO:') || content.includes('FIXME:')) {
+        warnings.push({
+          type: 'INDEX_PENDING_CHANGES',
+          message: `"${module.name}/index.ts" tiene TODO/FIXME. Revisar antes de continuar.`,
+        })
+      }
+    } catch { /* no index */ }
+  }
+
+  // Verificar que los conectores existen si hay más de 1 módulo (REGLA CLAUDE #5)
+  if (modules.length > 1 && connectors.length === 0) {
+    violations.push({
+      type: 'MISSING_CONNECTORS',
+      module: 'system',
+      message: `Hay ${modules.length} módulos pero 0 conectores. Los módulos no están conectados. (CLAUDE #5)`,
+    })
+  }
+
+  // ── Los 6 que las reglas base no prevenían ──────────────────────
+
+  for (const module of modules) {
+    const modPath = join(modulesPath, module.name)
+
+    // 1. DOCUMENTACIÓN FALTANTE — descripción vacía en el módulo
+    const indexPath = join(modPath, 'index.ts')
+    try {
+      const indexContent = await readFile(indexPath, 'utf-8')
+      // Busca description: '' o description: " " en el createModule/export
+      if (/description:\s*['"`]\s*['"`]/.test(indexContent)) {
+        violations.push({
+          type: 'EMPTY_MODULE_DESCRIPTION',
+          module: module.name,
+          message: `"${module.name}" tiene descripción vacía. Todo módulo DEBE documentar su propósito.`,
+        })
+      }
+    } catch { /* no index — ya detectado */ }
+
+    // 2. TEST COVERAGE — archivo de test existe pero sin casos
+    const testPath = join(modPath, 'tests', 'service.test.ts')
+    try {
+      const testContent = await readFile(testPath, 'utf-8')
+      const hasTests = /\btest\s*\(|\bit\s*\(|\bdescribe\s*\(/.test(testContent)
+      if (!hasTests) {
+        violations.push({
+          type: 'TESTS_WITHOUT_CASES',
+          module: module.name,
+          message: `"${module.name}/tests/service.test.ts" existe pero no tiene ningún test(). Coverage = 0.`,
+        })
+      }
+    } catch { /* no test file — ya detectado por MISSING_TESTS */ }
+
+    // 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 */ }
+
+    // 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 */ }
+
+    // 5. GOD SERVICE — service con más de 200 líneas indica demasiadas responsabilidades
+    const servicePath = join(modPath, 'actions', 'service.ts')
+    try {
+      const serviceContent = await readFile(servicePath, 'utf-8')
+      const lineCount = serviceContent.split('\n').length
+      if (lineCount > 200) {
+        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.`,
+        })
+      }
+    } catch { /* no service */ }
+
+    // 6. SERVICE CRUZA MÓDULO — service importa de otro módulo directamente
+    try {
+      const serviceContent = await readFile(servicePath, 'utf-8')
+      for (const other of modules) {
+        if (other.name === module.name) continue
+        const importPattern = new RegExp(`from ['"][^'"]*\\/modules\\/${other.name}([/'"]|\$)`)
+        if (importPattern.test(serviceContent)) {
+          violations.push({
+            type: 'SERVICE_IMPORTS_OTHER_MODULE',
+            module: module.name,
+            message: `"${module.name}/service.ts" importa de "${other.name}". Los services no pueden cruzar módulos — usar conector. (CLAUDE #1)`,
+          })
+        }
+      }
+    } catch { /* no service */ }
+
+    // 7. N+1 RISK — ORM llamado dentro de un loop en el service
+    try {
+      const serviceContent = await readFile(servicePath, 'utf-8')
+      const lines = serviceContent.split('\n')
+      let insideLoop = 0
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? ''
+        // Detectar apertura de loop
+        if (/\b(for\s*\(|forEach\s*\(|\.map\s*\(\s*async|\.filter\s*\(\s*async|while\s*\()/.test(line)) insideLoop++
+        // Detectar cierre de bloque (aproximación por llaves)
+        const opens = (line.match(/\{/g) ?? []).length
+        const closes = (line.match(/\}/g) ?? []).length
+        if (insideLoop > 0 && closes > opens) insideLoop = Math.max(0, insideLoop - 1)
+        // Detectar ORM dentro del loop
+        if (insideLoop > 0 && /await\s+\w*orm\w*\.(findMany|findById|create|update|delete|count|paginate)\s*\(/.test(line)) {
+          violations.push({
+            type: 'N_PLUS_ONE_RISK',
+            module: module.name,
+            message: `"${module.name}/service.ts" línea ${i + 1}: ORM llamado dentro de un loop — riesgo de N+1. Usar findMany/createMany/updateMany fuera del loop.`,
+          })
+          break // un warning por archivo es suficiente
+        }
+      }
+    } 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
+          }
+        }
+      }
+    } catch { /* no service */ }
+
+    // 9. SERVICE DEPENDS ON ORM — service inyecta ORM en lugar de RepositoryAdapter (Regla #18)
+    try {
+      const serviceContent = await readFile(servicePath, 'utf-8')
+      // Detectar: private orm: ORM  o  private readonly orm: ORM  en el constructor
+      if (/private\s+(readonly\s+)?\w+\s*:\s*ORM\b/.test(serviceContent)) {
+        violations.push({
+          type: 'SERVICE_DEPENDS_ON_ORM',
+          module: module.name,
+          message: `"${module.name}/service.ts" inyecta ORM directamente. Usar RepositoryAdapter<T> para poder swapear SQL → MongoDB → Prisma sin tocar el service. (CLAUDE #18)`,
+        })
+      }
+    } catch { /* no service */ }
+  }
+
+  return {
+    valid: violations.length === 0,
+    modules,
+    connectors,
+    violations,
+    warnings,
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try { await access(path); return true } catch { return false }
+}
+
+async function getAllTsFiles(dir: string): Promise<string[]> {
+  const files: string[] = []
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== 'tests' && entry.name !== '__tests__') {
+          files.push(...await getAllTsFiles(full))
+        }
+      } else if (entry.name.endsWith('.ts')) {
+        files.push(full)
+      }
+    }
+  } catch { /* ignore */ }
+  return files
+}
+
+export function printAnalysis(result: AnalysisResult): void {
+  console.log('\n══════════════════════════════════════')
+  console.log('  Análisis de Arquitectura')
+  console.log('══════════════════════════════════════\n')
+
+  console.log(`📦 Módulos (${result.modules.length}):`)
+  for (const m of result.modules) {
+    const icon = m.hasIndex ? '✓' : '✗'
+    const parts = [
+      m.hasService ? 'service' : null,
+      m.hasController ? 'controller' : null,
+      m.hasTypes ? 'types' : null,
+      m.hasSockets ? 'sockets' : null,
+      m.hasValidators ? 'validators' : null,
+      m.hasTests ? 'tests' : null,
+    ].filter(Boolean)
+    console.log(`   ${icon} ${m.name} [${parts.join(', ')}]`)
+  }
+
+  console.log(`\n🔌 Conectores (${result.connectors.length}):`)
+  for (const c of result.connectors) {
+    console.log(`   ${c}`)
+  }
+
+  if (result.violations.length > 0) {
+    // Agrupar por categoría para que la IA sepa exactamente qué arreglar
+    const byCategory: Record<string, Violation[]> = {
+      'Estructura': [],
+      'Acoplamiento': [],
+      'Diseño': [],
+      'Calidad': [],
+      'Seguridad': [],
+      'Performance': [],
+      'Portabilidad': [],
+    }
+
+    for (const v of result.violations) {
+      if (['MISSING_INDEX', 'MISSING_SERVICE', 'MISSING_TYPES', 'MISSING_SOCKETS', 'MISSING_VALIDATORS', 'MISSING_TESTS', 'MISSING_CONNECTORS', 'EMPTY_MODULE_DESCRIPTION'].includes(v.type)) {
+        byCategory['Estructura']!.push(v)
+      } else if (['DIRECT_MODULE_IMPORT', 'SERVICE_IMPORTS_OTHER_MODULE', 'CONNECTOR_BUSINESS_LOGIC'].includes(v.type)) {
+        byCategory['Acoplamiento']!.push(v)
+      } else if (['BUSINESS_LOGIC_IN_CONTROLLER', 'GOD_SERVICE', 'INDEX_PENDING_CHANGES'].includes(v.type)) {
+        byCategory['Diseño']!.push(v)
+      } else if (['IDOR_RISK'].includes(v.type)) {
+        byCategory['Seguridad']!.push(v)
+      } else if (['N_PLUS_ONE_RISK'].includes(v.type)) {
+        byCategory['Performance']!.push(v)
+      } else if (['SERVICE_DEPENDS_ON_ORM'].includes(v.type)) {
+        byCategory['Portabilidad']!.push(v)
+      } else {
+        byCategory['Calidad']!.push(v)
+      }
+    }
+
+    console.log(`\n❌ Violaciones (${result.violations.length}):`)
+    for (const [cat, vs] of Object.entries(byCategory)) {
+      if (vs.length === 0) continue
+      console.log(`\n   [${cat}]`)
+      for (const v of vs) console.log(`     • ${v.message}`)
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    console.log(`\n⚠️  Advertencias (${result.warnings.length}):`)
+    for (const w of result.warnings) {
+      console.log(`   ${w.message}`)
+    }
+  }
+
+  console.log(`\n📊 Resultado: ${result.valid ? '✅ VÁLIDO' : '❌ VIOLACIONES ENCONTRADAS'}`)
+  console.log('══════════════════════════════════════\n')
+}
+
+/**
+ * Genera el objeto arckode.json — snapshot del sistema legible por la IA.
+ * La IA lee este archivo PRIMERO para conocer el estado del proyecto
+ * sin tener que parsear 1800+ líneas del kernel ni todos los módulos.
+ */
+export function buildManifest(result: AnalysisResult): Record<string, unknown> {
+  return {
+    _arckode: '1.0.0',
+    _generated: new Date().toISOString(),
+    _instructions: 'Lee este archivo ANTES de escribir código. Contiene el estado completo del sistema: módulos, conectores, violaciones. Si está desactualizado, corré: bun run analyze --json',
+
+    system: {
+      healthy: result.valid,
+      violations: result.violations.length,
+      warnings: result.warnings.length,
+    },
+
+    modules: result.modules.map(m => ({
+      name: m.name,
+      structure: {
+        index:       m.hasIndex,
+        types:       m.hasTypes,
+        sockets:     m.hasSockets,
+        service:     m.hasService,
+        controller:  m.hasController,
+        validators:  m.hasValidators,
+        tests:       m.hasTests,
+      },
+      complete: m.hasIndex && m.hasTypes && m.hasService && m.hasController && m.hasValidators && m.hasTests,
+    })),
+
+    connectors: result.connectors,
+
+    violations: result.violations.map(v => ({
+      module:  v.module,
+      type:    v.type,
+      message: v.message,
+    })),
+
+    warnings: result.warnings.map(w => ({
+      type:    w.type,
+      message: w.message,
+    })),
+
+    rules_summary: [
+      'REGLA 1: Módulos NO importan de otros módulos. Usar conectores.',
+      'REGLA 2: index.ts es APPEND-ONLY. No eliminar exports.',
+      'REGLA 3: Conectores NO tienen lógica de negocio. Solo delegan.',
+      'REGLA 4: Cada tabla pertenece a UN módulo.',
+      'REGLA 5: Si no está en composition-root.ts, no existe.',
+      'REGLA 6: Todo POST/PUT/PATCH requiere validateSchema().',
+      'REGLA 7: Controller NO llama al ORM. Llama al service.',
+      'REGLA 18: Service recibe RepositoryAdapter<T>, no ORM directamente.',
+    ],
+  }
+}

package/cli/commands/db-migrate.ts

@@ -0,0 +1,121 @@
+// cli/commands/db-migrate.ts — Ejecuta migraciones SQL versionadas
+// Corre los archivos de src/migrations/*.ts que tienen up() / down()
+// Usa _arckode_migrations para rastrear cuáles ya se aplicaron
+
+import Database from 'better-sqlite3'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+
+async function readDbPath(basePath: string): Promise<string> {
+  const envFile = join(basePath, '.env')
+  if (existsSync(envFile)) {
+    const content = await readFile(envFile, 'utf-8')
+    const match = content.match(/^DB_PATH=(.+)$/m)
+    if (match?.[1]) return match[1].trim()
+  }
+  return './data/db.sqlite'
+}
+
+interface DbRunner {
+  run(sql: string, params?: unknown[]): void
+  exec(sql: string): void
+}
+
+export async function dbMigrate(direction: 'up' | 'down' = 'up') {
+  const basePath = process.cwd()
+  const migrationsDir = join(basePath, 'src', 'migrations')
+
+  if (!existsSync(migrationsDir)) {
+    console.error('❌ No se encuentra src/migrations/')
+    console.error('   Creá una con: arckode make:migration <nombre>')
+    return
+  }
+
+  const dbRelPath = await readDbPath(basePath)
+  const dbAbsPath = resolve(basePath, dbRelPath)
+
+  const db = new Database(dbAbsPath)
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _arckode_migrations (
+      name TEXT PRIMARY KEY,
+      direction TEXT NOT NULL,
+      runAt TEXT NOT NULL
+    )
+  `)
+
+  const files = (await readdir(migrationsDir))
+    .filter(f => f.endsWith('.ts') || f.endsWith('.js'))
+    .sort()
+
+  if (files.length === 0) {
+    console.log('📭 No hay archivos en src/migrations/')
+    db.close()
+    return
+  }
+
+  const applied = new Set<string>(
+    (db.prepare('SELECT name FROM _arckode_migrations WHERE direction = ?').all('up') as { name: string }[])
+      .map(r => r.name)
+  )
+
+  const runner: DbRunner = {
+    run(sql, params = []) { db.prepare(sql).run(...params) },
+    exec(sql) { db.exec(sql) },
+  }
+
+  if (direction === 'up') {
+    const pending = files.filter(f => !applied.has(f))
+
+    if (pending.length === 0) {
+      console.log('✅ No hay migraciones pendientes')
+      db.close()
+      return
+    }
+
+    for (const file of pending) {
+      const filePath = join(migrationsDir, file)
+      const migration = await import(filePath)
+
+      if (typeof migration.up !== 'function') {
+        console.warn(`⚠️  ${file} no exporta up() — saltando`)
+        continue
+      }
+
+      console.log(`▶ Aplicando: ${file}`)
+      await migration.up(runner)
+      db.prepare('INSERT INTO _arckode_migrations (name, direction, runAt) VALUES (?, ?, ?)')
+        .run(file, 'up', new Date().toISOString())
+      console.log(`✅ ${file}`)
+    }
+
+    console.log(`\n${pending.length} migración(es) aplicada(s)`)
+  } else {
+    // down: revertir la última aplicada
+    const last = db.prepare('SELECT name FROM _arckode_migrations WHERE direction = ? ORDER BY runAt DESC LIMIT 1')
+      .get('up') as { name: string } | undefined
+
+    if (!last) {
+      console.log('📭 No hay migraciones para revertir')
+      db.close()
+      return
+    }
+
+    const filePath = join(migrationsDir, last.name)
+    const migration = await import(filePath)
+
+    if (typeof migration.down !== 'function') {
+      console.error(`❌ ${last.name} no exporta down()`)
+      db.close()
+      return
+    }
+
+    console.log(`▶ Revirtiendo: ${last.name}`)
+    await migration.down(runner)
+    db.prepare('DELETE FROM _arckode_migrations WHERE name = ?').run(last.name)
+    console.log(`✅ Revertida: ${last.name}`)
+  }
+
+  db.close()
+}

package/cli/commands/db-seed.ts

@@ -0,0 +1,54 @@
+// cli/commands/db-seed.ts — Comando arckode db:seed
+// Ejecuta los seeds definidos en el composition root
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+
+export async function dbSeed(seedName?: string) {
+  const basePath = process.cwd()
+  const crPath = join(basePath, 'src', 'composition-root.ts')
+
+  if (!existsSync(crPath)) {
+    console.error('❌ No se encuentra src/composition-root.ts')
+    console.error('   Ejecutá este comando desde la raíz del proyecto.')
+    return
+  }
+
+  // Leer seeds/ y detectar archivos disponibles
+  const seedsPath = join(basePath, 'src', 'seeds')
+  if (!existsSync(seedsPath)) {
+    console.error('❌ No hay directorio src/seeds/')
+    console.error('   Creá seeds con: arckode make:seed <Nombre>')
+    return
+  }
+
+  const { readdir } = await import('node:fs/promises')
+  const seedFiles = (await readdir(seedsPath)).filter(f => f.endsWith('.ts'))
+
+  if (seedFiles.length === 0) {
+    console.log('📭 No hay seeds para ejecutar.')
+    return
+  }
+
+  if (seedName) {
+    const file = seedFiles.find(f => f.startsWith(seedName))
+    if (!file) {
+      console.error(`❌ Seed "${seedName}" no encontrado.`)
+      console.log(`   Seeds disponibles: ${seedFiles.join(', ')}`)
+      return
+    }
+    console.log(`🌱 Ejecutando seed: ${file}`)
+    // La IA o el usuario debe agregar la lógica en composition-root según el seed
+    console.log(`   Para ejecutarlo, corré: RUN_SEEDS=true bun run src/composition-root.ts`)
+    return
+  }
+
+  console.log('🌱 Seeds disponibles:')
+  for (const file of seedFiles) {
+    console.log(`   - ${file.replace('.ts', '')}`)
+  }
+  console.log('')
+  console.log('   Para ejecutar todos: RUN_SEEDS=true bun run src/composition-root.ts')
+  console.log('   Para ejecutar uno:   bun arckode db:seed <nombre>')
+}