@gzl10/nexus-backend 0.12.7 → 0.13.0

package/AGENTS.md

@@ -0,0 +1,386 @@
+# Backend AGENTS.md
+
+`@gzl10/nexus-backend` - BaaS library (Express 5 + Knex + CASL)
+
+## Commands
+
+```bash
+pnpm dev           # Hot reload (tsx watch)
+pnpm build         # Build (tsup)
+pnpm typecheck     # Type check
+pnpm test          # Vitest
+
+# Database migrations
+pnpm migrate create <name>  # Generate migration from entities
+pnpm migrate up             # Run pending migrations
+pnpm migrate down           # Rollback last batch
+pnpm migrate status         # Show migration status
+pnpm migrate reset          # Reset DB (dev only)
+```
+
+## Directory Structure
+
+```text
+src/
+├── config/          # Env vars, NexusConfig, DB config (NO lógica)
+├── db/              # Conexión Knex, sistema de migraciones, SQL utils
+│   ├── migrations/  # Archivos de migración versionados (.ts)
+│   ├── migration-runner.ts     # Ejecutor con batches
+│   ├── migration-generator.ts  # Generador automático
+│   ├── migration-lock.ts       # Sistema de bloqueo
+│   ├── schema-reader.ts        # Lector de esquema DB
+│   └── migration-helpers.ts    # Utilidades Knex
+├── engine/          # Registro módulos, contexto, carga
+├── runtime/         # Services, controllers, factories para entities
+├── core/            # Express app, server, middleware, Socket.IO
+└── modules/         # Lógica de negocio (entities, routes, services)
+```
+
+### Reglas de Dependencias
+
+- \`modules/\` → NO importa de otros modules (usa \`ctx.services\`)
+- \`engine/\` → NO importa de modules (solo tipos genéricos)
+- \`config/\` → Solo configuración, NO conexiones ni lógica
+- \`db/connection.ts\` → Gestión conexión Knex (separado de config)
+
+## Database Migrations
+
+Sistema estilo Prisma con generación automática de migraciones desde entity definitions.
+
+### Workflow
+
+**Desarrollo rápido:**
+1. Modificar entities en \`src/modules/*/\`
+2. \`pnpm migrate dev\` - Genera y aplica migración automáticamente
+
+**Desarrollo con revisión:**
+1. Modificar entities en \`src/modules/*/\`
+2. \`pnpm migrate create add_email_field\` - Genera migración comparando entities vs schema actual
+3. Revisar archivo generado en \`migrations/{timestamp}_add_email_field.ts\`
+4. \`pnpm migrate up\` - Ejecutar migraciones pendientes
+5. \`pnpm migrate down\` - Rollback si es necesario
+
+### Archivos de Migración
+
+Formato: \`{timestamp}_{name}.ts\`
+
+\`\`\`typescript
+import type { Knex } from 'knex'
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('users', (table) => {
+    table.string('id', 26).primary()
+    table.string('email', 255).notNullable().unique()
+    table.timestamp('created_at').defaultTo(knex.fn.now())
+  })
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('users')
+}
+\`\`\`
+
+### Sistema de Tracking
+
+- Tabla \`_nexus_migrations\`: registra migraciones ejecutadas con batch, status, execution_time
+- Tabla \`_nexus_migration_lock\`: previene ejecución concurrente (detecta PIDs muertos)
+- Batches: agrupa migraciones ejecutadas juntas para rollback coordinado
+
+### Producción
+
+Migraciones se ejecutan automáticamente en startup del servidor:
+
+\`\`\`typescript
+await ensureMigrationTables(getDb())
+await runMigrations() // Falla = servidor no inicia
+\`\`\`
+
+### UI
+
+Entity \`migration-history\` en módulo \`system\` (solo lectura, ADMIN/SUPPORT):
+- Ver historial completo de migraciones
+- Status: completed, failed, rolled_back
+- Tiempos de ejecución, errores, batches
+
+## Module Structure
+
+```text
+src/modules/{name}/
+├── index.ts           # Manifest + barrel exports (tipos incluidos)
+├── {name}.entity.ts   # EntityDefinitions
+├── {name}.types.ts    # Tipos + ServiceInterface
+├── {name}.service.ts  # Lógica de negocio
+└── {name}.routes.ts   # Rutas custom (opcional)
+```
+
+**Barrel exports obligatorios:** Tipos de servicio exportados desde `index.ts`
+
+## Actions Organization
+
+Cuando un módulo tiene múltiples actions, organizarlas en carpeta `actions/`:
+
+```text
+src/modules/{name}/
+├── actions/
+│   ├── helpers.ts           # Funciones compartidas (cookies, request info, rate limits)
+│   ├── {action-name}.action.ts  # Un archivo por action
+│   └── index.ts             # Re-exports + array de actions
+├── index.ts
+└── ...
+```
+
+**Estructura de un action file:**
+
+```typescript
+// login.action.ts
+import type { ActionDefinition } from '@gzl10/nexus-sdk'
+import { createAuthService } from '../auth.service.js'
+import { getCookieOptions, getRequestInfo, createRateLimits } from './helpers.js'
+
+export const loginAction: ActionDefinition = {
+  type: 'action',
+  key: 'login',                    // Ruta: /api/v1/{module}/{key}
+  label: { en: 'Login', es: 'Iniciar sesión' },
+  icon: 'mdi:login',
+  scope: 'module',                 // module | entity | row
+  method: 'POST',
+  middleware: (ctx) => createRateLimits(ctx).login,
+  fields: {
+    email: { name: 'email', input: 'email', required: true, label: { en: 'Email' } },
+    password: { name: 'password', input: 'password', required: true, label: { en: 'Password' } }
+  },
+  handler: async (ctx, input, req, res) => {
+    const body = input as LoginInput
+    const authService = createAuthService(ctx)
+    const result = await authService.login(body, getRequestInfo(req!))
+    res!.cookie('refreshToken', result.refreshToken, getCookieOptions(req!))
+    return { user: result.user, accessToken: result.accessToken }
+  }
+}
+```
+
+**Scope routing:**
+
+| Scope    | Ruta resultante                         |
+| -------- | --------------------------------------- |
+| `module` | `/api/v1/{module}/{action}`             |
+| `entity` | `/api/v1/{module}/{entity}/{action}`    |
+| `row`    | `/api/v1/{module}/{entity}/:id/{action}`|
+
+**actions/index.ts:**
+
+```typescript
+import type { ActionDefinition } from '@gzl10/nexus-sdk'
+export { loginAction } from './login.action.js'
+export { logoutAction } from './logout.action.js'
+// ...
+
+import { loginAction } from './login.action.js'
+import { logoutAction } from './logout.action.js'
+
+export const authActions: Array<ActionDefinition & { type: 'action' }> = [
+  loginAction,
+  logoutAction
+] as Array<ActionDefinition & { type: 'action' }>
+```
+
+**En module/index.ts:**
+
+```typescript
+import { authActions } from './actions/index.js'
+
+export const authModule: ModuleManifest = {
+  definitions: [
+    someEntity,
+    ...authActions  // Se auto-montan y documentan en OpenAPI
+  ]
+}
+```
+
+## Patterns
+
+**Comunicación entre módulos:**
+
+```typescript
+// En init(): registrar
+ctx.services['users'] = createUsersService(ctx)
+
+// En otro módulo: usar (tipar con import del módulo)
+const users = ctx.services['users'] as UsersService
+```
+
+**ESM imports:** Siempre con extensión `.js`
+
+**Knex count:** `.first<{ count: string | number }>()`
+
+**EventEmitter2:** `import pkg from 'eventemitter2'; const { EventEmitter2 } = pkg`
+
+## CASL Authorization
+
+Roles: `OWNER`, `ADMIN`, `MANAGER`, `EDITOR`, `CONTRIBUTOR`, `USER`, `VIEWER`, `SUPPORT`, `AUDITOR`, `DEVELOPER`, `BOT`, `SERVICE`
+
+Actions: `create`, `read`, `update`, `delete`, `manage`
+
+## Testing
+
+`tests/runtime/` - Unit tests con `createMockContext()` de `test-helpers.ts`
+
+`tests/migration-*.test.ts` - Tests del sistema de migraciones (SQLite, PostgreSQL, MySQL)
+
+## Ejemplos de Uso
+
+### Entity Definitions
+
+```typescript
+// reference entity - catálogos estáticos
+export const categories: ReferenceEntityDefinition = {
+  key: 'categories',
+  type: 'reference',
+  labelField: 'name',
+  fields: {
+    name: { type: 'text', required: true },
+    code: { type: 'text', required: true }
+  },
+  seed: [
+    { name: 'Technology', code: 'tech' },
+    { name: 'Science', code: 'sci' }
+  ]
+}
+
+// single entity - configuración singleton
+export const siteConfig: SingleEntityDefinition = {
+  key: 'site_config',
+  type: 'single',
+  defaults: {
+    siteName: 'My App',
+    logo: '/logo.png',
+    theme: 'light'
+  }
+}
+
+// tree entity - estructura jerárquica
+export const departments: TreeEntityDefinition = {
+  key: 'departments',
+  type: 'tree',
+  labelField: 'name',
+  fields: {
+    name: { type: 'text', required: true },
+    code: { type: 'text' }
+  },
+  seed: [
+    { id: '1', name: 'Engineering', parent_id: null },
+    { id: '2', name: 'Frontend', parent_id: '1' }
+  ]
+}
+
+// dag entity - grafo acíclico dirigido
+export const workflows: DagEntityDefinition = {
+  key: 'workflows',
+  type: 'dag',
+  labelField: 'name',
+  fields: {
+    name: { type: 'text', required: true },
+    status: { type: 'select', options: ['pending', 'active', 'done'] }
+  }
+}
+```
+
+### Service Usage
+
+```typescript
+// SingleService - get/set config
+const configService = new SingleService(ctx, siteConfig)
+const config = await configService.get()          // Returns defaults if not in DB
+await configService.set({ siteName: 'New Name' }) // Merge update
+await configService.reset()                       // Reset to defaults
+
+// TreeService - hierarchical operations
+const deptService = new TreeService(ctx, departments)
+const children = await deptService.findChildren('1')
+const ancestors = await deptService.findAncestors('2')
+const tree = await deptService.findTree()         // Full tree structure
+
+// DagService - graph operations
+const workflowService = new DagService(ctx, workflows)
+await workflowService.addEdge('node1', 'node2')
+const deps = await workflowService.findDependencies('node2')
+const deps = await workflowService.findDependents('node1')
+```
+
+### Seed Configuration
+
+```typescript
+// Inline array (simple)
+seed: [{ name: 'Item 1' }, { name: 'Item 2' }]
+
+// SeedConfig object (advanced)
+seed: {
+  source: 'url',
+  url: 'https://api.example.com/data.json',
+  headers: { 'Authorization': 'Bearer token' }
+}
+
+// seed() method persists data to DB at startup
+const service = new ReferenceService(ctx, definition)
+const count = await service.seed() // Returns number of records seeded
+```
+
+## Plugin Store
+
+Sistema de gestión de plugins desde la UI. Permite instalar, desinstalar y activar/desactivar plugins en caliente.
+
+### Entidades
+
+```typescript
+// Estado de activación de plugins (persistido en DB)
+pluginStateEntity: SingleEntityDefinition  // system module
+// key: 'plugin_state', defaults: { plugins: {} }
+// plugins: Record<string, boolean> - packageName -> enabled
+
+// Catálogo de plugins disponibles en npm
+pluginStoreEntity: ExternalEntityDefinition  // system module
+// key: 'plugin_store'
+// Obtiene datos de npm registry, no persiste en DB
+```
+
+### Actions
+
+| Action | Scope | Descripción |
+| ------ | ----- | ----------- |
+| `install-plugin` | module | Instala plugin desde npm (`pnpm add`) |
+| `uninstall-plugin` | module | Desinstala plugin (`pnpm remove`) |
+| `toggle-plugin` | module | Activa/desactiva plugin (actualiza `plugin_state`) |
+
+### Servicio
+
+```typescript
+// NpmRegistryService - consulta npm registry
+const npmService = new NpmRegistryService(ctx)
+const packages = await npmService.searchPlugins()  // Busca @gzl10/nexus-plugin-*
+const details = await npmService.getPackageDetails('@gzl10/nexus-plugin-ai')
+```
+
+### Helper
+
+```typescript
+// shouldLoadPlugin - determina si cargar un plugin
+import { shouldLoadPlugin } from './system.helpers.js'
+
+// Retorna true si:
+// 1. Plugin está instalado (existe en node_modules)
+// 2. Plugin no está explícitamente desactivado en plugin_state
+const load = await shouldLoadPlugin(ctx, '@gzl10/nexus-plugin-ai')
+```
+
+### Configuración
+
+```bash
+# Habilitar instalación de plugins desde UI (deshabilitado por defecto)
+NEXUS_ALLOW_PLUGIN_INSTALL=true
+```
+
+Cuando `NEXUS_ALLOW_PLUGIN_INSTALL=false`, las acciones `install-plugin` y `uninstall-plugin` retornan error 403.
+
+## Referencia detallada
+
+Ver KB Notion: "Backend Files Reference" y "Patrones" para documentación completa.

package/README.md

@@ -153,18 +153,17 @@ await start({
 ## CLI
 
 ```bash
-npx nexus start    # Start server
-npx nexus migrate  # Run migrations
-npx nexus seed     # Seed database
-```
-
-## Development
-
-```bash
-pnpm dev           # Start dev server
-pnpm build         # Build for production
-pnpm typecheck     # Type check
-pnpm test          # Run tests
+# Database migrations
+pnpm migrate dev            # Generate and apply migration (like Prisma)
+pnpm migrate create <name>  # Generate migration from entities
+pnpm migrate up             # Run pending migrations
+pnpm migrate down           # Rollback last batch
+pnpm migrate status         # Show migration status
+pnpm migrate reset          # Reset database (dev only)
+
+# Development
+pnpm dev     # Start dev server
+pnpm seed    # Seed database
 ```
 
 ## Stack