@gzl10/nexus-sdk 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -114,7 +114,7 @@ type DbType = 'string' | 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | '
 /**
  * Tipos de input en UI
  */
-type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'textarea' | 'markdown' | 'select' | 'multiselect' | 'tags' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'fileArray' | 'image' | 'imageArray' | 'hidden';
+type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'textarea' | 'markdown' | 'json' | 'select' | 'multiselect' | 'tags' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'fileArray' | 'image' | 'imageArray' | 'hidden';
 /**
  * Configuración de base de datos para un campo
  */
@@ -159,6 +159,7 @@ interface FieldOptions {
         value: string;
         label: string;
     }>;
+    allowCreate?: boolean;
 }
 /**
  * Restricciones de acceso CASL para un campo
@@ -214,7 +215,7 @@ interface FieldDefinition {
     hint?: string;
     hidden?: boolean;
     disabled?: boolean;
-    db: FieldDbConfig;
+    db?: FieldDbConfig;
     relation?: FieldRelation;
     validation?: FieldValidationConfig;
     options?: FieldOptions;
@@ -279,6 +280,63 @@ interface EntityCaslConfig {
      */
     sensitiveFields?: string[];
 }
+/**
+ * Action vinculada a un registro de la entidad
+ * Define operaciones que actúan sobre registros existentes
+ *
+ * Ruta generada: GET|POST /{entityRoutePrefix}/{key}/:id
+ *
+ * @example
+ * ```typescript
+ * actions: [{
+ *   key: 'download',
+ *   label: 'Download File',
+ *   icon: 'mdi:download',
+ *   method: 'GET',
+ *   select: ['id', 'filename', 'mimetype'],
+ *   handler: async (ctx, input, _req, res) => {
+ *     const { _record: file, _authUserId } = input
+ *     // file y _authUserId vienen inyectados automáticamente
+ *   }
+ * }]
+ * ```
+ */
+interface EntityAction {
+    /** Key única para la ruta (ej: 'download' → /download/:id) */
+    key: string;
+    /** Label para UI */
+    label: string;
+    /** Icono Iconify (default: 'mdi:play') */
+    icon?: string;
+    /** Método HTTP (default: 'POST') */
+    method?: 'GET' | 'POST';
+    /** Campos a seleccionar del registro (default: todos) */
+    select?: string[];
+    /** Schema de validación del body (opcional) */
+    inputSchema?: ValidationSchema;
+    /** Schema del output (documentación) */
+    outputSchema?: ValidationSchema;
+    /** Middleware custom (ej: multer) */
+    middleware?: (ctx: ModuleContext) => RequestHandler | RequestHandler[];
+    /**
+     * Handler - recibe _record y _authUserId automáticamente
+     * @param ctx - Contexto del módulo
+     * @param input - Body validado + _record + _authUserId
+     * @param req - Express Request
+     * @param res - Express Response (para streams, headers custom)
+     */
+    handler: (ctx: ModuleContext, input: unknown, req?: Request, res?: Response) => Promise<unknown>;
+    /**
+     * Permisos CASL específicos para esta action
+     * Si no se define, hereda los permisos de la entidad padre
+     */
+    casl?: {
+        /** Action CASL (default: 'execute') */
+        action?: string;
+        /** Conditions adicionales */
+        conditions?: Record<string, unknown>;
+    };
+}
 /**
  * Propiedades base compartidas por todas las EntityDefinition
  */
@@ -293,6 +351,8 @@ interface BaseEntityDefinition {
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar (default: inferido de table) */
     routePrefix?: string;
+    /** Orden de visualización en UI (menor = primero, default: 999) */
+    order?: number;
 }
 /**
  * Entidad de colección - CRUD completo (users, posts, orders)
@@ -310,6 +370,8 @@ interface CollectionEntityDefinition extends BaseEntityDefinition {
     indexes?: EntityIndex[];
     /** Usar deleted_at en vez de DELETE físico */
     softDelete?: boolean;
+    /** Actions vinculadas a registros de esta entidad */
+    actions?: EntityAction[];
 }
 /**
  * Entidad singleton - Un solo registro en tabla compartida sys_settings
@@ -334,6 +396,8 @@ interface SingleEntityDefinition {
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar (default: inferido de key) */
     routePrefix?: string;
+    /** Actions vinculadas a esta entidad single */
+    actions?: EntityAction[];
 }
 /**
  * Entidad de referencia - Catálogos con CRUD admin (countries, currencies)
@@ -370,23 +434,43 @@ interface EventEntityDefinition extends BaseEntityDefinition {
 }
 /**
  * Entidad de acción - Comandos/operaciones sin persistencia
+ * Para actions que operan sobre registros existentes, usar EntityAction en la entidad padre
  */
 interface ActionEntityDefinition {
     type: 'action';
     /** Nombre para mostrar en UI */
     label: string;
+    /** Icono Iconify para UI (default: 'mdi:play') */
+    icon?: string;
     /** Solo campos de formulario para input, sin BD */
     fields: Record<string, FieldDefinition>;
     /** Schema Zod de input (se valida antes de ejecutar) */
     inputSchema?: ValidationSchema;
     /** Schema Zod de output (documenta respuesta) */
     outputSchema?: ValidationSchema;
-    /** Handler que ejecuta la acción */
-    handler?: (ctx: ModuleContext, input: unknown) => Promise<unknown>;
+    /** Método HTTP (default: POST) */
+    method?: 'GET' | 'POST';
+    /**
+     * Middleware a aplicar antes del handler (ej: multer para uploads)
+     * Puede retornar un middleware o un array de middlewares
+     */
+    middleware?: (ctx: ModuleContext) => RequestHandler | RequestHandler[];
+    /**
+     * Handler que ejecuta la acción
+     * @param ctx - Contexto del módulo
+     * @param input - Datos del body. Incluye _authUserId si hay usuario autenticado.
+     * @param req - Request de Express (opcional, para acceder a req.file, etc.)
+     * @param res - Response de Express (opcional, para streams, headers custom, etc.)
+     */
+    handler?: (ctx: ModuleContext, input: unknown, req?: Request, res?: Response) => Promise<unknown>;
+    /** HTTP status code para respuesta exitosa (default: 200, usar 201 para creación) */
+    successStatus?: number;
     /** Autorización CASL */
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar */
     routePrefix?: string;
+    /** Orden de visualización en UI (menor = primero, default: 999) */
+    order?: number;
 }
 /**
  * Entidad externa - Datos de APIs externas (stripe_customers, github_repos)
@@ -422,6 +506,8 @@ interface ExternalEntityDefinition {
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar */
     routePrefix?: string;
+    /** Orden de visualización en UI (menor = primero, default: 999) */
+    order?: number;
 }
 /**
  * Entidad virtual - Orquestación de múltiples fuentes (unified_customers)
@@ -443,6 +529,8 @@ interface VirtualEntityDefinition {
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar */
     routePrefix?: string;
+    /** Orden de visualización en UI (menor = primero, default: 999) */
+    order?: number;
 }
 /**
  * Entidad computed - KPIs, estadísticas, métricas calculadas
@@ -469,6 +557,8 @@ interface ComputedEntityDefinition {
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar */
     routePrefix?: string;
+    /** Orden de visualización en UI (menor = primero, default: 999) */
+    order?: number;
 }
 /**
  * Entidad view - Vista optimizada para lectura (projections, denormalizaciones)
@@ -492,6 +582,8 @@ interface ViewEntityDefinition {
     casl?: EntityCaslConfig;
     /** Prefijo de ruta para montar */
     routePrefix?: string;
+    /** Orden de visualización en UI (menor = primero, default: 999) */
+    order?: number;
 }
 /**
  * Entidad config - Configuración por módulo/tenant
@@ -600,9 +692,56 @@ interface ContextHelpers {
     generateId: () => string;
     addTimestamps: (table: Knex.CreateTableBuilder, db: Knex) => void;
     addAuditFieldsIfMissing: (db: Knex, tableName: string) => Promise<void>;
+    /** Añade campo is_default a tablas de tipo config */
+    addConfigDefaultField: (db: Knex, tableName: string) => Promise<void>;
     addColumnIfMissing: (db: Knex, tableName: string, columnName: string, columnBuilder: (table: Knex.AlterTableBuilder) => void) => Promise<boolean>;
     getLibPath: () => string;
     getProjectPath: () => string;
+    /** Timestamp formateado para el driver de BD actual (MySQL: 'YYYY-MM-DD HH:MM:SS', otros: ISO 8601) */
+    nowTimestamp: (db: Knex) => string;
+    /** Formatea una fecha para el driver de BD actual */
+    formatTimestamp: (db: Knex, date?: Date) => string;
+}
+/**
+ * Utilidades criptográficas del contexto
+ */
+interface ContextCrypto {
+    /** Hash de password usando bcrypt (cost factor 12) */
+    hashPassword: (password: string) => Promise<string>;
+    /** Verifica password contra hash bcrypt (timing-safe) */
+    verifyPassword: (password: string, hash: string) => Promise<boolean>;
+    /** Hash dummy para timing-safe comparison cuando usuario no existe */
+    DUMMY_HASH: string;
+}
+/**
+ * API de Socket.IO del contexto
+ * @note Solo disponible si Socket.IO está inicializado
+ */
+interface ContextSocket {
+    /** Obtiene la instancia de Socket.IO (throws si no inicializado) */
+    getIO: () => unknown;
+    /** Verifica si Socket.IO está inicializado */
+    isInitialized: () => boolean;
+    /** Verifica si un usuario específico está conectado */
+    isUserConnected: (userId: string) => boolean;
+    /** Obtiene el número de sockets conectados para un usuario */
+    getUserSocketCount: (userId: string) => number;
+    /** Obtiene los IDs de usuarios conectados */
+    getConnectedUsers: () => string[];
+}
+/**
+ * API del Engine para introspección de módulos y plugins
+ * Permite acceder al registro de módulos y plugins cargados
+ */
+interface ContextEngine {
+    /** Obtiene todos los módulos registrados */
+    getModules: () => ModuleManifest[];
+    /** Obtiene todos los plugins registrados */
+    getPlugins: () => PluginManifest[];
+    /** Obtiene los subjects CASL de un módulo específico */
+    getModuleSubjects: (mod: ModuleManifest) => string[];
+    /** Obtiene todos los subjects CASL registrados en el sistema */
+    getRegisteredSubjects: () => string[];
 }
 /**
  * Schema de validación genérico (compatible con Zod sin depender de él)
@@ -780,31 +919,16 @@ interface ConfigEntityService<T = unknown> extends BaseEntityService<T> {
     set(key: string, value: unknown, userId?: string): Promise<T>;
     getAll(): Promise<Record<string, unknown>>;
 }
-/**
- * Servicio para entidades Reference (lectura con join automático)
- */
-interface ReferenceEntityService<T = unknown> extends BaseEntityService<T> {
-}
-/**
- * Servicio para entidades View (vista SQL, solo lectura)
- */
-interface ViewEntityService<T = unknown> extends BaseEntityService<T> {
-}
-/**
- * Servicio para entidades Computed (campos calculados, solo lectura)
- */
-interface ComputedEntityService<T = unknown> extends BaseEntityService<T> {
-}
-/**
- * Servicio para entidades External (datos de API externa)
- */
-interface ExternalEntityService<T = unknown> extends BaseEntityService<T> {
-}
-/**
- * Servicio para entidades Virtual (orquestación de múltiples fuentes)
- */
-interface VirtualEntityService<T = unknown> extends BaseEntityService<T> {
-}
+/** Servicio para entidades Reference (lectura con join automático) */
+type ReferenceEntityService<T = unknown> = BaseEntityService<T>;
+/** Servicio para entidades View (vista SQL, solo lectura) */
+type ViewEntityService<T = unknown> = BaseEntityService<T>;
+/** Servicio para entidades Computed (campos calculados, solo lectura) */
+type ComputedEntityService<T = unknown> = BaseEntityService<T>;
+/** Servicio para entidades External (datos de API externa) */
+type ExternalEntityService<T = unknown> = BaseEntityService<T>;
+/** Servicio para entidades Virtual (orquestación de múltiples fuentes) */
+type VirtualEntityService<T = unknown> = BaseEntityService<T>;
 /**
  * Servicio para entidades Action (ejecutar acciones)
  */
@@ -892,12 +1016,20 @@ interface ModuleContext {
     db: Knex;
     logger: Logger;
     helpers: ContextHelpers;
+    /** Utilidades criptográficas (hashPassword, verifyPassword) */
+    crypto: ContextCrypto;
+    /** API de Socket.IO para comunicación en tiempo real */
+    socket: ContextSocket;
+    /** API del Engine para introspección de módulos y plugins */
+    engine: ContextEngine;
     createRouter: () => Router;
     middleware: ModuleMiddlewares;
     /** Configuración resuelta de la aplicación */
     config: Record<string, unknown>;
     errors: {
-        AppError: new (message: string, statusCode?: number) => Error;
+        AppError: new (message: string, statusCode?: number, details?: unknown) => Error & {
+            details?: unknown;
+        };
         NotFoundError: new (message?: string) => Error;
         UnauthorizedError: new (message?: string) => Error;
         ForbiddenError: new (message?: string) => Error;
@@ -997,4 +1129,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-export { type AbilityLike, type ActionEntityDefinition, type ActionEntityService, type AuthRequest, type BaseEntityService, type BaseMailService, type BaseRolesService, type BaseUser, type BaseUsersService, CATEGORIES, CATEGORY_ORDER, type CaslAction, type Category, type CategoryMeta, type CollectionEntityDefinition, type CollectionEntityService, type ComputedEntityDefinition, type ComputedEntityService, type ConfigEntityDefinition, type ConfigEntityService, type ContextHelpers, type CoreServices, type CreateEntityServiceOptions, type DbType, type EntityCaslConfig, type EntityController, type EntityDefinition, type EntityHandler, type EntityIndex, type EntityQuery, type EntityServiceHooks, type EntityType, type EventEmitterLike, type EventEntityDefinition, type EventEntityService, type ExternalEntityDefinition, type ExternalEntityService, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type LoggerReporter, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginManifest, type ReferenceEntityDefinition, type ReferenceEntityService, type RolePermission, type SendMailOptions, type SendMailResult, type SingleEntityDefinition, type SingleEntityService, type TempEntityDefinition, type TempEntityService, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type ViewEntityService, type VirtualEntityDefinition, type VirtualEntityService, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };
+export { type AbilityLike, type ActionEntityDefinition, type ActionEntityService, type AuthRequest, type BaseEntityService, type BaseMailService, type BaseRolesService, type BaseUser, type BaseUsersService, CATEGORIES, CATEGORY_ORDER, type CaslAction, type Category, type CategoryMeta, type CollectionEntityDefinition, type CollectionEntityService, type ComputedEntityDefinition, type ComputedEntityService, type ConfigEntityDefinition, type ConfigEntityService, type ContextCrypto, type ContextEngine, type ContextHelpers, type ContextSocket, type CoreServices, type CreateEntityServiceOptions, type DbType, type EntityAction, type EntityCaslConfig, type EntityController, type EntityDefinition, type EntityHandler, type EntityIndex, type EntityQuery, type EntityServiceHooks, type EntityType, type EventEmitterLike, type EventEntityDefinition, type EventEntityService, type ExternalEntityDefinition, type ExternalEntityService, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type LoggerReporter, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginManifest, type ReferenceEntityDefinition, type ReferenceEntityService, type RolePermission, type SendMailOptions, type SendMailResult, type SingleEntityDefinition, type SingleEntityService, type TempEntityDefinition, type TempEntityService, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type ViewEntityService, type VirtualEntityDefinition, type VirtualEntityService, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gzl10/nexus-sdk",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "SDK types for creating Nexus plugins and modules",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,22 +23,12 @@
   ],
   "author": "Gonzalo Díez <gonzalo@gzl10.com>",
   "license": "MIT",
-  "homepage": "https://www.gzl10.com",
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.gzl10.com/oss/nexus-sdk"
-  },
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/gzl10"
-  },
   "devDependencies": {
     "@types/express": "^5.0.2",
     "express": "^5.0.1",
     "knex": "^3.1.0",
     "pino": "^9.6.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.3"
+    "tsup": "^8.4.0"
   },
   "peerDependencies": {
     "express": "^5.0.1",
@@ -62,6 +52,8 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "clean": "rm -rf dist node_modules"
   }
 }

package/README.md

@@ -1,321 +0,0 @@
-# @gzl10/nexus-sdk
-
-TypeScript SDK for creating plugins and modules compatible with [Nexus Backend](https://gitlab.gzl10.com/oss/nexus-backend).
-
-Define module and plugin manifests with full type safety without depending on the full `@gzl10/nexus-backend` package.
-
-## Installation
-
-```bash
-npm install @gzl10/nexus-sdk
-# or
-pnpm add @gzl10/nexus-sdk
-```
-
-## Usage
-
-### Define a module
-
-```typescript
-import type { ModuleManifest, PluginAuthRequest } from '@gzl10/nexus-sdk'
-
-export const tasksModule: ModuleManifest = {
-  name: 'tasks',
-  label: 'Tasks',
-  icon: 'mdi:checkbox-marked-outline',
-  description: 'Task management',
-
-  dependencies: ['users'],
-
-  migrate: async (ctx) => {
-    const { db, helpers } = ctx
-    const exists = await db.schema.hasTable('tasks')
-    if (!exists) {
-      await db.schema.createTable('tasks', (table) => {
-        table.string('id').primary()
-        table.string('title').notNullable()
-        table.text('description')
-        table.boolean('completed').defaultTo(false)
-        table.string('created_by').references('id').inTable('users')
-        helpers.addTimestamps(table, db)
-      })
-    }
-  },
-
-  routes: (ctx) => {
-    const router = ctx.createRouter()
-    const { abilities, services } = ctx
-
-    router.get('/', async (req: PluginAuthRequest, res) => {
-      // Check permissions with CASL
-      abilities.ForbiddenError.from(req.ability).throwUnlessCan('read', 'tasks')
-
-      const tasks = await ctx.db('tasks').select('*')
-
-      // Resolve user relations
-      const userIds = [...new Set(tasks.map(t => t.created_by).filter(Boolean))]
-      const users = await services.users?.findByIds(userIds) ?? []
-
-      res.json({ tasks, users })
-    })
-
-    return router
-  },
-
-  entities: [
-    {
-      name: 'tasks',
-      label: 'Tasks',
-      labelField: 'title',
-      listFields: { title: 'Title', completed: 'Completed' },
-      formFields: {
-        title: { label: 'Title', type: 'text', required: true },
-        description: { label: 'Description', type: 'textarea' },
-        completed: { label: 'Completed', type: 'checkbox' }
-      }
-    }
-  ]
-}
-```
-
-### Define a plugin (groups modules)
-
-```typescript
-import type { PluginManifest } from '@gzl10/nexus-sdk'
-import { tasksModule } from './modules/tasks'
-import { projectsModule } from './modules/projects'
-
-export const projectPlugin: PluginManifest = {
-  name: '@myorg/nexus-projects',
-  label: 'Projects',
-  icon: 'mdi:folder-outline',
-  category: 'content',
-  version: '1.0.0',
-  description: 'Project management plugin',
-  modules: [tasksModule, projectsModule]
-}
-```
-
-## EntityDefinition (v0.2.0+)
-
-Define entities as single source of truth for DB, validation, UI, and CASL:
-
-```typescript
-import type { EntityDefinition } from '@gzl10/nexus-sdk'
-
-export const postEntity: EntityDefinition = {
-  table: 'cms_posts',
-  label: 'Posts',
-  labelField: 'title',
-  timestamps: true,
-  audit: true,
-
-  fields: {
-    id: {
-      name: 'id',
-      label: 'ID',
-      input: 'hidden',
-      db: { type: 'uuid', nullable: false, defaultFn: 'uuid' }
-    },
-    title: {
-      name: 'title',
-      label: 'Title',
-      input: 'text',
-      db: { type: 'string', size: 200, nullable: false },
-      validation: { required: true, min: 3, max: 200 },
-      meta: { searchable: true, sortable: true }
-    },
-    content: {
-      name: 'content',
-      label: 'Content',
-      input: 'markdown',
-      db: { type: 'text', nullable: true }
-    },
-    status: {
-      name: 'status',
-      label: 'Status',
-      input: 'select',
-      db: { type: 'string', nullable: false, default: 'draft' },
-      validation: { enum: ['draft', 'published', 'archived'] },
-      options: {
-        static: [
-          { value: 'draft', label: 'Draft' },
-          { value: 'published', label: 'Published' },
-          { value: 'archived', label: 'Archived' }
-        ]
-      }
-    }
-  },
-
-  casl: {
-    ownership: { field: 'created_by' },
-    permissions: {
-      ADMIN: { actions: ['manage'] },
-      EDITOR: { actions: ['create', 'read', 'update'] },
-      VIEWER: { actions: ['read'] }
-    }
-  }
-}
-```
-
-### Code Generators
-
-Generate TypeScript interfaces from EntityDefinitions:
-
-```typescript
-import { generateModel, generateModelsFile } from '@gzl10/nexus-sdk'
-
-// Generate TypeScript interface for a single entity
-const modelCode = generateModel(postEntity)
-// Creates: export interface Post { ... }
-
-// Generate models file for multiple entities
-const modelsFile = generateModelsFile([postEntity, userEntity])
-// Creates consolidated models file with all interfaces
-```
-
-> **Note:** Zod schemas and migrations are now generated at runtime by `@gzl10/nexus-backend`.
-
-## CLI (v0.5.0+)
-
-Generate TypeScript models from EntityDefinitions in your modules:
-
-```bash
-# Install globally or use npx
-npx @gzl10/nexus-sdk generate
-
-# Generate for all modules in src/modules
-nexus-sdk generate --path src/modules
-
-# Generate for specific module
-nexus-sdk generate --module users
-
-# Watch mode for development
-nexus-sdk generate --watch
-
-# Dry run (preview without writing)
-nexus-sdk generate --dry-run --verbose
-```
-
-### CLI Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `-p, --path <dir>` | `src/modules` | Base modules directory |
-| `-m, --module <name>` | - | Generate only specific module |
-| `-o, --output <dir>` | `__generated__` | Output directory name |
-| `-w, --watch` | - | Watch for changes and regenerate |
-| `--dry-run` | - | Show what would be generated |
-| `--verbose` | - | Show detailed logs |
-
-### Generated Files
-
-For each module with `definitions`, the CLI generates:
-
-```text
-src/modules/posts/
-├── index.ts              # Module manifest with definitions
-└── __generated__/
-    └── posts.models.ts   # TypeScript interfaces
-```
-
-### Module Structure
-
-The CLI discovers modules by looking for `index.ts` files that export a `ModuleManifest` with `definitions`:
-
-```typescript
-// src/modules/posts/index.ts
-import type { ModuleManifest, EntityDefinition } from '@gzl10/nexus-sdk'
-
-const postEntity: EntityDefinition = {
-  type: 'collection',
-  table: 'posts',
-  // ...
-}
-
-export const postsModule: ModuleManifest = {
-  name: 'posts',
-  label: 'Posts',
-  definitions: [postEntity]
-}
-```
-
-## Main Types
-
-### Manifests & Context
-
-| Type | Description |
-|------|-------------|
-| `ModuleManifest` | Defines a module: routes, migrations, seeds, entities |
-| `PluginManifest` | Groups modules under a plugin with shared metadata |
-| `ModuleContext` | Context injected by Nexus: `db`, `logger`, `helpers`, `services`, `abilities` |
-
-### Entity Definition System
-
-| Type | Description |
-|------|-------------|
-| `EntityDefinition` | Complete entity definition (DB, UI, validation, CASL) |
-| `FieldDefinition` | Field configuration with DB, UI, and validation settings |
-| `FieldDbConfig` | Database column configuration |
-| `FieldRelation` | Foreign key configuration |
-| `EntityCaslConfig` | CASL authorization configuration |
-
-### Entity Types (Discriminated Union)
-
-| Type | Description |
-|------|-------------|
-| `CollectionEntity` | Full CRUD (users, posts) |
-| `ReferenceEntity` | Catalogs with admin CRUD (countries) |
-| `SingleEntity` | Singleton, update/read only (site_config) |
-| `ConfigEntity` | Per-module config, singleton |
-| `ExternalEntity` | Read-only from external systems |
-| `VirtualEntity` | Orchestration of multiple sources |
-| `ComputedEntity` | KPIs, calculated stats |
-| `ViewEntity` | Optimized read projections |
-| `EventEntity` | Audit logs, append-only |
-| `TempEntity` | TTL-based (cache, sessions) |
-| `ActionEntity` | Commands without persistence |
-
-### Request & Auth
-
-| Type | Description |
-|------|-------------|
-| `AuthRequest<TUser, TAbility>` | Generic authenticated request |
-| `PluginAuthRequest` | Pre-typed `AuthRequest<BaseUser, AbilityLike>` for plugins |
-| `BaseUser` | User without password for relations |
-| `AbilityLike` | Generic CASL ability interface (`can`, `cannot`) |
-
-### Services & Utilities
-
-| Type | Description |
-|------|-------------|
-| `EntityType` | Union of all entity type strings |
-| `PaginationParams` | Pagination input (`page`, `limit`) |
-| `PaginatedResult<T>` | Paginated response with metadata |
-| `ValidationSchema` | Generic Zod-compatible schema interface |
-
-### ModuleContext
-
-The context provides access to:
-
-- `db` - Knex instance for queries
-- `logger` - Pino logger
-- `helpers` - Migration utilities (`addTimestamps`, `addColumnIfMissing`)
-- `createRouter()` - Express Router factory
-- `middleware.validate()` - Request validation with Zod schemas
-- `errors` - Error classes (`AppError`, `NotFoundError`, `UnauthorizedError`, etc.)
-- `abilities` - CASL helpers (`subject`, `ForbiddenError`)
-- `services` - Registered services (extensible)
-- `events` - EventEmitter for inter-module communication
-- `mail` - Email sending service
-
-### Re-exported Types
-
-For convenience, the SDK re-exports commonly used types:
-
-- **Express:** `Request`, `Response`, `NextFunction`, `RequestHandler`, `Router`, `CookieOptions`
-- **Knex:** `Knex`, `KnexCreateTableBuilder`, `KnexAlterTableBuilder`, `KnexTransaction`
-
-## License
-
-MIT © [Gonzalo Díez](https://www.gzl10.com)