arckode-framework 1.3.1 → 1.4.0

package/skills/cli/SKILL.md

@@ -1,267 +1,48 @@
-# SKILL: Arckode CLI — Generadores y Comandos
+# CLI — Generadores y Comandos
 
-> Activar cuando: crear módulo nuevo, generar código, correr migraciones, analizar arquitectura, listar rutas.
+## Stack
 
----
+Commander.js + custom handlers.
 
-## 1. COMANDOS DISPONIBLES
+## Comandos actuales
 
-```bash
-arckode new <nombre>                    # Crear proyecto nuevo
-arckode make:module <Nombre>            # Generar módulo completo (7 archivos)
-arckode make:connector <nombre> <m1> <m2>  # Generar conector entre módulos
-arckode make:migration <descripcion>    # Crear archivo de migración SQL
-arckode make:seed <nombre>             # Crear archivo de seed
-arckode make:auth                      # Generar módulo de autenticación completo
-arckode analyze                        # Detectar violaciones de arquitectura
-arckode analyze --strict               # Idem, falla con exit 1 si hay violaciones
-arckode routes                         # Listar todas las rutas del proyecto
-arckode db:migrate                     # Correr migraciones pendientes
-arckode db:migrate --rollback          # Revertir última migración
-```
-
----
-
-## 2. `arckode make:module` — Lo que genera
-
-```bash
-arckode make:module Producto
-```
-
-Genera en `src/modules/producto/` (nueva estructura):
-```
-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)
+| Comando | Descripción |
+|---------|-------------|
+| `arckode new:module <name>` | Scaffold módulo canónico |
+| `arckode make:controller <mod> <name>` | Crea controller |
+| `arckode make:service <mod> <name>` | Crea service |
+| `arckode make:model <mod> <name>` | Crea model + types |
+| `arckode analyze` | Static analysis del módulo actual |
+| `arckode --help` | Todos los comandos |
 
-`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.
+## Arquitectura de comando
 
-**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`
-
-**Después de generar:**
-1. Revisar `types.ts` → ajustar campos al dominio real
-2. Revisar `validators/schema.ts` → ajustar validaciones
-3. Agregar a `composition-root.ts`:
-   ```ts
-   import { ProductoModel } from './modules/producto/types'
-   import { ProductoModule } from './modules/producto'
-
-   orm.define('Producto', ProductoModel)
-   system.addModule(ProductoModule())
-   ```
-
----
-
-## 3. `arckode make:connector` — Lo que genera
-
-```bash
-arckode make:connector pedido-inventario pedidos inventario
-```
-
-Genera `src/connectors/pedido-inventario.ts`:
 ```ts
-import type { ConnectorContext } from 'arckode-framework'
-import type { PedidosService }    from '../modules/pedidos'
-import type { InventarioService } from '../modules/inventario'
-
-export function conectarPedidoConInventario(ctx: ConnectorContext): void {
-  const pedidos    = ctx.resolveModule<PedidosService>('pedidos')
-  const inventario = ctx.resolveModule<InventarioService>('inventario')
-
-  // TODO: inyectar sockets
-  pedidos.setSockets({
-    // onEventoEjemplo: async (data) => { await inventario.accion(data) }
+// src/cli/commands/new-module.command.ts
+import { Command } from 'commander'
+export const newModuleCommand = new Command('new:module')
+  .argument('<name>', 'module name')
+  .action(async (name) => {
+    await scaffoldModule(name) // → llama al scaffold, no lógica inline
   })
-}
 ```
 
-**Después de generar:**
-1. Implementar los sockets necesarios
-2. Agregar a `composition-root.ts`:
-   ```ts
-   import { conectarPedidoConInventario } from './connectors/pedido-inventario'
-   system.addConnector('pedido-inventario', conectarPedidoConInventario)
-   ```
-
----
-
-## 4. `arckode analyze` — Violaciones detectadas
-
-```bash
-arckode analyze
-```
-
-Output ejemplo:
-```
-🔍 Analizando proyecto...
-
-❌ 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/controller.ts:23
-   "router.post sin validateSchema()"
-   → Todo POST debe validar el body antes de llamar al service.
-
-⚠️  MISSING_SOCKETS             modules/usuarios/
-   → El módulo no tiene sockets.ts
-
-✅ Sin violaciones en: pedidos, inventario, auth
-
-Resumen: 2 errores, 1 advertencia
-```
-
-**Violaciones críticas (❌):** Deben corregirse antes del merge.
-**Advertencias (⚠️):** Recomendadas pero no bloqueantes.
-
-### Tabla completa de checks
-
-| Código | Severidad | Descripción |
-|--------|-----------|-------------|
-| `MISSING_INDEX` | ❌ | Módulo sin index.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/ |
-| `MISSING_SOCKETS` | ⚠️ | Sin sockets.ts |
-| `MISSING_CONNECTORS` | ⚠️ | 2+ módulos sin conectores definidos |
-| `DIRECT_MODULE_IMPORT` | ❌ | Un módulo importa de otro |
-| `CONNECTOR_BUSINESS_LOGIC` | ❌ | Conector con if/for/lógica |
-| `CONTROLLER_MISSING_VALIDATION` | ❌ | POST/PUT/PATCH sin validateSchema |
-| `BUSINESS_LOGIC_IN_CONTROLLER` | ❌ | ORM directo en controller |
-| `EMPTY_MODULE_DESCRIPTION` | ❌ | description: '' en createModule |
-| `TESTS_WITHOUT_CASES` | ❌ | Archivo test sin test() |
-| `SERVICE_IMPORTS_OTHER_MODULE` | ❌ | Service importa de otro módulo |
-| `GOD_SERVICE` | ⚠️ | Service > 200 líneas |
-| `N_PLUS_ONE_RISK` | ⚠️ | ORM dentro de loop |
-| `IDOR_RISK` | ❌ | findById sin assertOwnership |
-| `SERVICE_DEPENDS_ON_ORM` | ❌ | Service recibe ORM, no RepositoryAdapter |
-
----
-
-## 5. `arckode routes` — Ver rutas registradas
+Registrar en `index.ts`:
 
-```bash
-arckode routes
-```
-
-Output:
-```
-GET    /productos
-POST   /productos          [validate: crearProductoSchema]
-GET    /productos/:id
-PUT    /productos/:id      [auth: admin] [validate: actualizarProductoSchema]
-DELETE /productos/:id      [auth: admin]
-POST   /auth/login
-POST   /auth/registro
-POST   /auth/refresh
-```
-
----
-
-## 6. `arckode db:migrate` — Migraciones SQL
-
-```bash
-# Ver pendientes y correrlos
-arckode db:migrate
-
-# Revertir último
-arckode db:migrate --rollback
-```
-
-**Tabla de control:** `_arckode_migrations` (columnas: name, runAt, direction)
-
-**Los archivos de migración van en `src/migrations/`:**
-```
-src/migrations/
-  1716000000_create_productos.ts
-  1716100000_add_stock_to_productos.ts
-  1716200000_add_index_pedidos_usuario.ts
-```
-
-El timestamp en el nombre determina el orden de ejecución.
-
----
-
-## 7. `arckode new` — Proyecto desde cero
-
-```bash
-arckode new mi-api
-cd mi-api
-```
-
-Genera:
-```
-mi-api/
-├── src/
-│   ├── composition-root.ts   ← con loadEnv(), ORM, Router, System
-│   └── modules/
-│       └── .gitkeep
-├── .env.example
-├── .gitignore
-├── CLAUDE.md                 ← apunta a este skill
-├── package.json              ← arckode-framework como dependencia
-└── tsconfig.json             ← strict mode
-```
-
----
-
-## 8. INTEGRAR CON CI/CD
-
-```yaml
-# .github/workflows/ci.yml
-- name: Analyze architecture
-  run: arckode analyze --strict  # falla el CI si hay violaciones
-
-- name: Run tests
-  run: bun test
-
-- name: Type check
-  run: bun run --bun tsc --noEmit
+```ts
+program.addCommand(newModuleCommand)
 ```
 
----
-
-## 9. WORKFLOW COMPLETO — Agregar feature
-
-```bash
-# 1. Generar el módulo
-arckode make:module Pago
-
-# 2. Ajustar types.ts con los campos reales
+## Cómo extender
 
-# 3. Ajustar validators/schema.ts
+1. Crear archivo en `src/cli/commands/`
+2. Función handler separada en `src/cli/handlers/`
+3. Exportar e importar en `cli/index.ts`
 
-# 4. Implementar service.ts (lógica de negocio)
+## Troubleshooting
 
-# 5. Si se conecta con otro módulo
-arckode make:connector pago-pedido pagos pedidos
-
-# 6. Agregar a composition-root.ts
-
-# 7. Si necesita migración SQL
-arckode make:migration add_pagos_table
-
-# 8. Verificar todo
-bun run src/composition-root.ts  # sin errores TypeScript
-arckode analyze                  # 0 violaciones críticas
-bun test modules/pago            # tests pasan
-arckode routes                   # rutas visibles
-```
+| Problema | Causa | Fix |
+|----------|-------|-----|
+| Comando no registrado | `index.ts` sin `addCommand` | Import + add |
+| Handler pesado | Lógica inline en action | Separar en handler |
+| Sin validación | `argument('<name>')` sin name | Input normalizado en handler |

package/skills/config/SKILL.md

@@ -1,253 +1,44 @@
-# SKILL: Arckode Config — ConfigStore, Logger y Cache
+# Config — ENV, Entorno, Jerarquía
 
-> Activar cuando: configurar variables de entorno, agregar config nueva, usar el logger, trabajar con cache.
+## Stack
 
----
+`process.env` + archivo `config.ts` por módulo.
 
-## 1. CONFIGSTORE + loadEnv
+## Jerarquía
 
-### Setup completo
-
-```ts
-import { ConfigStore, loadEnv } from 'arckode-framework'
-
-// 1. Cargar archivos .env (SIEMPRE await)
-const env = await loadEnv()
-
-// 2. Definir schema y cargar valores
-const config = new ConfigStore()
-config
-  .define({
-    // Servidor
-    PORT:        { type: 'number',  default: 3000 },
-    HOST:        { type: 'string',  default: '0.0.0.0' },
-    NODE_ENV:    { type: 'string',  default: 'development' },
-
-    // Base de datos
-    DB_PATH:     { type: 'string',  default: './data/db.sqlite' },
-    DB_HOST:     { type: 'string',  required: false },
-    DB_PORT:     { type: 'number',  default: 5432 },
-    DB_NAME:     { type: 'string',  required: false },
-    DB_USER:     { type: 'string',  required: false },
-    DB_PASSWORD: { type: 'string',  required: false },
-
-    // Auth
-    JWT_SECRET:  { type: 'string',  required: true },    // fail-fast si falta
-
-    // Opcionales con defaults
-    LOG_LEVEL:   { type: 'string',  default: 'info' },
-    SMTP_HOST:   { type: 'string',  required: false },
-    SMTP_PORT:   { type: 'number',  default: 587 },
-  })
-  .load(env)
 ```
-
-### Tipos de config disponibles
-
-| Tipo | Validación | Ejemplo |
-|------|-----------|---------|
-| `string` | Cualquier texto | `'localhost'` |
-| `number` | Parseado de string | `'3000'` → `3000` |
-| `boolean` | `'true'/'false'/'1'/'0'` | `'true'` → `true` |
-| `url` | Válida como URL | `'https://api.com'` |
-| `email` | Válido como email | `'a@b.com'` |
-
-### Opciones por campo
-
-```ts
-config.define({
-  CAMPO: {
-    type:     'string',      // tipo (requerido)
-    required: true,          // fail-fast si no está en .env — default: false
-    default:  'valor',       // valor si no está en .env
-    // required + default no tienen sentido juntos — elegir uno
-  }
-})
+process.env.*          ← values directos
+src/shared/config.ts   ← defaults + validación
+modules/{mod}/config.ts ← overrides del módulo
 ```
 
-### Leer valores
-
 ```ts
-config.get('PORT')               // → string (tipo no inferido)
-config.get<number>('PORT')       // → number (con genérico)
-config.get<boolean>('DEBUG')     // → boolean
-config.get('JWT_SECRET')         // → string
-
-// Fail-fast en get(): si la key no fue definida → error en startup
-```
-
-### Archivos .env cargados (en orden de precedencia)
-
-```
-process.env                  ← máxima prioridad (CI/CD, Docker)
-.env.{NODE_ENV}.local        ← ej: .env.development.local
-.env.{NODE_ENV}              ← ej: .env.production
-.env.local                   ← local, no commitear
-.env                         ← base del proyecto
-```
-
-**.gitignore obligatorio:**
-```gitignore
-.env.local
-.env.*.local
-.env.production
-```
-
----
-
-## 2. LOGGER
-
-### Crear logger
-
-```ts
-import { Logger } from 'arckode-framework'
-
-// En composition-root
-const logger = new Logger('app', 'info')    // nombre, log level
-
-// Logger hijo por módulo (recomendado)
-const log = logger.child('productos')       // → [app.productos]
-const log = logger.child('productos.stock') // → [app.productos.stock]
-```
-
-### Niveles disponibles: `debug` | `info` | `warn` | `error`
-
-```ts
-log.debug('Mensaje de debug', { userId, queryTime })   // solo si LOG_LEVEL=debug
-log.info('Operación completada', { id: item.id })
-log.warn('Comportamiento inesperado', { field, value })
-log.error('Error crítico', { error: err.message, stack: err.stack })
-```
-
-### Qué loguear y cómo
-
-```ts
-// ✅ Info: eventos de negocio con contexto suficiente para debugging
-log.info('Pedido confirmado', { pedidoId, usuarioId, total })
-log.info('Usuario registrado', { userId, email })
-
-// ✅ Warn: comportamiento inusual que no es error
-log.warn('Stock bajo', { productoId, stockActual: 3, umbral: 10 })
-log.warn('Token próximo a expirar', { userId, expiresIn: '5min' })
-
-// ✅ Error: errores reales con contexto completo
-log.error('Fallo al enviar email', { to, error: err.message })
-
-// ❌ Debug en producción — usar solo en desarrollo
-log.debug('Query ejecutada', { sql, params, duration })
-
-// ❌ Nunca loguear datos sensibles
-log.info('Login', { email, password: dto.password })  // NO
-log.info('Login', { email })                           // ✅
-```
-
-### Log level por entorno
-
-```env
-# .env
-LOG_LEVEL=info
-
-# .env.development
-LOG_LEVEL=debug
-```
-
----
-
-## 3. CACHE
-
-### Setup
-
-```ts
-import { MemoryCache } from 'arckode-framework'
-
-const cache = new MemoryCache()
-
-// Para producción distribuida → Redis
-import { RedisCache } from 'arckode-framework/adapters/redis-cache'
-const cache = new RedisCache({ host: config.get('REDIS_HOST'), port: 6379 })
-```
-
-### API del Cache
-
-```ts
-// Leer
-const value = await cache.get<ProductoDTO[]>('productos:list')  // null si no existe o expiró
-
-// Guardar con TTL (en segundos)
-await cache.set('productos:list', items, 60)     // expira en 60s
-await cache.set('usuario:123', user, 300)        // expira en 5 min
-await cache.set('config:global', data)           // sin TTL — persiste hasta flush()
-
-// Invalidar
-await cache.delete('productos:list')             // borrar una key
-await cache.flush()                              // borrar todo
-
-// Estadísticas
-console.log(cache.stats)
-// { size: 42, hits: 1203, misses: 87, hitRate: '93.27%' }
-```
-
-### Patrón cache-aside (el más común)
-
-```ts
-async listar(): Promise<ProductoDTO[]> {
-  const KEY = 'productos:list'
-
-  const cached = await this.cache.get<ProductoDTO[]>(KEY)
-  if (cached) return cached                              // cache HIT
-
-  const items = await this.repo.findMany({ activo: true })
-  await this.cache.set(KEY, items, 60)                   // guardar 60s
-  return items
+// src/shared/config.ts
+export const config = {
+  port: parseInt(process.env.PORT || '3000'),
+  db: {
+    host: process.env.DB_HOST || 'localhost',
+    port: parseInt(process.env.DB_PORT || '3306'),
+  },
+  jwt: {
+    secret: process.env.JWT_SECRET!,
+  },
 }
 ```
 
-### Invalidar al mutar
-
-```ts
-async crear(dto: CreateProductoDTO): Promise<ProductoDTO> {
-  const item = await this.repo.create(...)
-  await this.cache.delete('productos:list')   // invalidar lista
-  return item
-}
-
-async actualizar(id: string, dto: UpdateProductoDTO): Promise<ProductoDTO> {
-  const item = await this.repo.update(id, dto)
-  await this.cache.delete('productos:list')   // invalidar lista
-  await this.cache.delete(`producto:${id}`)  // invalidar el item específico
-  return item!
-}
-```
-
-### Naming convention de keys
-
-```
-{entidad}:list                    → productos:list
-{entidad}:{id}                    → producto:abc-123
-{entidad}:{id}:{sub-recurso}      → usuario:abc-123:pedidos
-{scope}:{entidad}:{filtro}        → admin:reportes:2026-05
-```
-
-### TTL recomendados
-
-| Tipo de dato | TTL |
-|-------------|-----|
-| Listas con paginación | 30-60s |
-| Item individual | 2-5 min |
-| Datos de config | 10-30 min |
-| Contadores/stats | 5 min |
-| Tokens/sessions | igual que el token |
-| Datos de referencia (países, categorías) | 1h+ |
+## .env requerido (sin default)
 
----
+| Var | Por qué |
+|-----|---------|
+| `JWT_SECRET` | Firma de tokens |
+| `DB_PASSWORD` | Acceso a DB |
+| `REDIS_URL` | Cache + colas |
 
-## 4. CHECKLIST CONFIG
+## Errores silenciosos
 
-- [ ] `loadEnv()` con `await` — nunca sincrónico
-- [ ] Keys `required: true` para todo lo que cause crash si falta
-- [ ] Nunca `config.get()` sin haber llamado `config.define()` antes
-- [ ] Logger hijo por módulo: `logger.child('nombre-modulo')`
-- [ ] Nunca loguear passwords, tokens ni datos sensibles
-- [ ] Cache invalidado en toda operación de escritura que afecte la key
-- [ ] TTL explícito en `cache.set()` para datos que cambian frecuentemente
-- [ ] `.env.production` en `.gitignore` — nunca commitear secrets
+| Error | Señal | Fix |
+|-------|-------|-----|
+| Config en runtime | `process.env.X` en controllers | Leer en `config.ts` startup |
+| Sin validación | `PORT` string vs number | `parseInt` + fallback |
+| `.env` en producción | Variables ausentes | Chequear en bootstrap |
+| Módulo override muta shared | `config.port = 3001` en módulo | Clonar o no mutar |