@gzl10/nexus-sdk 0.1.11 → 0.3.0

package/README.md

@@ -98,17 +98,131 @@ export const projectPlugin: PluginManifest = {
 }
 ```
 
+## 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 migrations, Zod schemas, TypeScript models, and CASL permissions:
+
+```typescript
+import {
+  generateMigration,
+  generateZodSchema,
+  generateModel,
+  generateCaslPermissions
+} from '@gzl10/nexus-sdk'
+
+// Generate Knex migration code
+const migrationCode = generateMigration(postEntity)
+
+// Generate Zod validation schemas
+const zodCode = generateZodSchema(postEntity)
+// Creates: createPostSchema, updatePostSchema, postParamsSchema, postQuerySchema
+
+// Generate TypeScript interface
+const modelCode = generateModel(postEntity)
+// Creates: export interface Post { ... }
+
+// Generate CASL permissions for seeding
+const permissions = generateCaslPermissions(postEntity)
+// Returns: Array<{ role, action, subject, conditions, fields, inverted }>
+```
+
 ## Main Types
 
 ### Manifests & Context
 
 | Type | Description |
 |------|-------------|
-| `ModuleManifest` | Defines a module: routes, migrations, seeds, CRUD entities |
+| `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` |
-| `ModuleEntity` | Declarative entity configuration for CRUD UI |
-| `FormField` | Form field configuration with validation |
+
+### 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
 

package/dist/index.d.ts

@@ -4,6 +4,85 @@ import { Request, RequestHandler, Router } from 'express';
 export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router } from 'express';
 import { Logger } from 'pino';
 
+/**
+ * Generadores de código desde EntityDefinition
+ *
+ * Estos generadores producen código TypeScript como strings
+ * que pueden ser escritos a archivos o usados en runtime.
+ */
+
+/**
+ * Entidades que persisten en BD local
+ * Excluye: action, external, virtual, computed
+ */
+type PersistentEntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition;
+/**
+ * Genera código de migración Knex desde EntityDefinition
+ *
+ * @example
+ * const code = generateMigration(postEntity)
+ * // Genera:
+ * // import type { ModuleContext, Knex } from '@gzl10/nexus-sdk'
+ * //
+ * // export async function migrate(ctx: ModuleContext): Promise<void> {
+ * //   const { db, logger, helpers } = ctx
+ * //   ...
+ * // }
+ */
+declare function generateMigration(entity: PersistentEntityDefinition): string;
+/**
+ * Genera código de schemas Zod desde EntityDefinition
+ *
+ * @example
+ * const code = generateZodSchema(postEntity)
+ * // Genera createPostSchema, updatePostSchema, postParamsSchema, postQuerySchema
+ */
+declare function generateZodSchema(entity: PersistentEntityDefinition): string;
+/**
+ * Genera interface TypeScript desde EntityDefinition
+ *
+ * @example
+ * const code = generateModel(postEntity)
+ * // Genera:
+ * // export interface Post {
+ * //   id: string
+ * //   title: string
+ * //   ...
+ * // }
+ */
+declare function generateModel(entity: PersistentEntityDefinition): string;
+/**
+ * Estructura de permiso generado para insertar en BD
+ */
+interface GeneratedPermission {
+    role: string;
+    action: string;
+    subject: string;
+    conditions: string | null;
+    fields: string | null;
+    inverted: boolean;
+}
+/**
+ * Genera permisos CASL desde EntityDefinition
+ *
+ * @example
+ * const permissions = generateCaslPermissions(postEntity)
+ * // Genera array de permisos para insertar en rol_role_permissions
+ */
+declare function generateCaslPermissions(entity: PersistentEntityDefinition): GeneratedPermission[];
+/**
+ * Genera código de seed para permisos CASL
+ *
+ * @example
+ * const code = generateCaslSeed([postEntity, pageEntity])
+ * // Genera código para insertar permisos en rol_role_permissions
+ */
+declare function generateCaslSeed(entities: EntityDefinition[]): string;
+/**
+ * Obtiene el subject CASL de una entidad
+ */
+declare function getEntitySubject(entity: PersistentEntityDefinition): string;
+
 /**
  * @gzl10/nexus-sdk
  *
@@ -11,6 +90,23 @@ import { Logger } from 'pino';
  * Use this package to define plugin/module manifests without
  * depending on the full @gzl10/nexus-backend package.
  */
+/**
+ * Unión discriminada de todos los tipos de entidad
+ *
+ * | Type       | Persistencia | CRUD            | Uso principal                    |
+ * |------------|--------------|-----------------|----------------------------------|
+ * | collection | Sí (BD)      | Completo        | Datos de negocio (users, posts)  |
+ * | single     | Sí (BD)      | Update/Read     | Config global (site_config)      |
+ * | external   | No           | Read            | Datos externos (stripe_customers)|
+ * | virtual    | No           | Read            | Orquestación (unified_customers) |
+ * | computed   | No/opcional  | Read            | KPIs, estadísticas               |
+ * | view       | Sí/virtual   | Read            | Lectura optimizada (projections) |
+ * | reference  | Sí           | Read (admin)    | Catálogos (countries, currencies)|
+ * | config     | Sí           | Update/Read     | Config por módulo                |
+ * | event      | Sí           | Append          | Auditoría (audit_logs)           |
+ * | temp       | No (TTL)     | Read/Write      | Cache, sesiones (otp_codes)      |
+ * | action     | No           | Execute         | Operaciones, workflows           |
+ */
 
 type KnexCreateTableBuilder = Knex.CreateTableBuilder;
 type KnexAlterTableBuilder = Knex.AlterTableBuilder;
@@ -93,18 +189,347 @@ interface FormField {
  */
 type ListType = 'table' | 'list' | 'grid' | 'masonry';
 /**
- * Configuración de una entidad/tabla del módulo para UI CRUD
+ * Tipos de columna en base de datos
+ */
+type DbType = 'string' | 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'json' | 'uuid';
+/**
+ * Tipos de input en UI
  */
-interface ModuleEntity {
+type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'textarea' | 'markdown' | 'select' | 'multiselect' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'image' | 'hidden';
+/**
+ * Configuración de base de datos para un campo
+ */
+interface FieldDbConfig {
+    type: DbType;
+    size?: number;
+    precision?: [number, number];
+    nullable: boolean;
+    unique?: boolean;
+    default?: unknown;
+    defaultFn?: 'now' | 'uuid';
+    index?: boolean;
+}
+/**
+ * Configuración de relación (Foreign Key)
+ */
+interface FieldRelation {
+    table: string;
+    column?: string;
+    onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+}
+/**
+ * Configuración de validación para un campo
+ */
+interface FieldValidationConfig {
+    required?: boolean;
+    min?: number;
+    max?: number;
+    pattern?: string;
+    format?: 'email' | 'url' | 'uuid' | 'slug';
+    enum?: string[];
+}
+/**
+ * Opciones para campos select/relaciones
+ */
+interface FieldOptions {
+    endpoint?: string;
+    valueField?: string;
+    labelField?: string;
+    static?: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+/**
+ * Restricciones de acceso CASL para un campo
+ */
+interface FieldCaslAccess {
+    /** Roles que pueden leer este campo (vacío = todos, null = nadie excepto ADMIN) */
+    readRoles?: string[];
+    /** Roles que pueden escribir este campo (vacío = todos, null = nadie excepto ADMIN) */
+    writeRoles?: string[];
+}
+/**
+ * Metadata del campo
+ */
+interface FieldMeta {
+    sortable?: boolean;
+    searchable?: boolean;
+    exportable?: boolean;
+    auditField?: 'created_by' | 'updated_by';
+    /** Restricciones de acceso CASL para este campo */
+    casl?: FieldCaslAccess;
+}
+/**
+ * Definición completa de un campo
+ *
+ * Contiene toda la información necesaria para:
+ * - UI: formularios, listas
+ * - BD: migraciones Knex
+ * - Validación: schemas Zod
+ */
+interface FieldDefinition {
     name: string;
     label: string;
-    listFields: Record<string, string>;
-    formFields?: Record<string, FormField>;
+    input: InputType;
+    placeholder?: string;
+    hint?: string;
+    hidden?: boolean;
+    disabled?: boolean;
+    db: FieldDbConfig;
+    relation?: FieldRelation;
+    validation?: FieldValidationConfig;
+    options?: FieldOptions;
+    meta?: FieldMeta;
+}
+/**
+ * Índice compuesto de tabla
+ */
+interface EntityIndex {
+    columns: string[];
+    unique?: boolean;
+}
+/**
+ * Acciones CASL estándar
+ */
+type CaslAction = 'manage' | 'create' | 'read' | 'update' | 'delete';
+/**
+ * Condición de ownership para permisos
+ * El campo de la entidad que referencia al usuario
+ */
+interface OwnershipCondition {
+    /** Campo que contiene el ID del propietario (ej: 'author_id', 'created_by') */
+    field: string;
+    /** Variable del usuario a comparar (default: 'id') */
+    userField?: string;
+}
+/**
+ * Permiso CASL para un rol específico
+ */
+interface RolePermission {
+    /** Acciones permitidas */
+    actions: CaslAction[];
+    /** Condiciones (ownership, status, etc.) */
+    conditions?: Record<string, unknown>;
+    /** Campos permitidos (null = todos) */
+    fields?: string[] | null;
+    /** Invertir permiso (cannot en lugar de can) */
+    inverted?: boolean;
+}
+/**
+ * Configuración de autorización CASL para una entidad
+ */
+interface EntityCaslConfig {
+    /**
+     * Subject CASL (default: inferido de table → 'cms_posts' → 'CmsPost')
+     */
+    subject?: string;
+    /**
+     * Campo de ownership para conditions automáticas
+     * Si se define, se genera condition { [field]: '${user.id}' }
+     */
+    ownership?: OwnershipCondition;
+    /**
+     * Permisos por rol
+     * Las keys son nombres de roles (ADMIN, EDITOR, VIEWER, etc.)
+     */
+    permissions?: Record<string, RolePermission>;
+    /**
+     * Campos sensibles que requieren permiso especial
+     * Se excluyen de 'read' para roles sin acceso explícito
+     */
+    sensitiveFields?: string[];
+}
+/**
+ * Propiedades base compartidas por todas las EntityDefinition
+ */
+interface BaseEntityDefinition {
+    /** Nombre de tabla en BD (con prefijo: 'cms_posts') */
+    table: string;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Definición de campos */
+    fields: Record<string, FieldDefinition>;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
+}
+/**
+ * Entidad de colección - CRUD completo (users, posts, orders)
+ * Default cuando no se especifica type
+ */
+interface CollectionEntityDefinition extends BaseEntityDefinition {
+    type?: 'collection';
+    /** Campo para mostrar en selects/referencias */
     labelField: string;
-    routePrefix?: string;
-    editMode?: 'modal' | 'page';
-    listType?: ListType;
+    /** Añadir created_at, updated_at */
+    timestamps?: boolean;
+    /** Añadir created_by, updated_by */
+    audit?: boolean;
+    /** Índices compuestos */
+    indexes?: EntityIndex[];
+}
+/**
+ * Entidad singleton - Solo Update/Read, sin lista (site_config)
+ */
+interface SingleEntityDefinition extends BaseEntityDefinition {
+    type: 'single';
+    /** Añadir updated_at */
+    timestamps?: boolean;
+    /** Añadir updated_by */
+    audit?: boolean;
+}
+/**
+ * Entidad de referencia - Catálogos con CRUD admin (countries, currencies)
+ */
+interface ReferenceEntityDefinition extends BaseEntityDefinition {
+    type: 'reference';
+    /** Campo para mostrar en selects/referencias */
+    labelField: string;
+    /** Añadir created_at, updated_at */
+    timestamps?: boolean;
+    /** Índices compuestos */
+    indexes?: EntityIndex[];
+}
+/**
+ * Entidad de eventos - Logs de auditoría, append-only
+ */
+interface EventEntityDefinition extends BaseEntityDefinition {
+    type: 'event';
+    /** Campo para mostrar en listas */
+    labelField: string;
+    /** Siempre true para eventos */
+    timestamps: true;
+}
+/**
+ * Entidad de acción - Comandos/operaciones sin persistencia
+ */
+interface ActionEntityDefinition {
+    type: 'action';
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Solo campos de formulario, sin BD */
+    fields: Record<string, FieldDefinition>;
+}
+/**
+ * Entidad externa - Datos de APIs externas (stripe_customers, github_repos)
+ * Read-only, sin persistencia local
+ */
+interface ExternalEntityDefinition {
+    type: 'external';
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
+    labelField: string;
+    /** Definición de campos (estructura esperada del API externo) */
+    fields: Record<string, FieldDefinition>;
+    /** Configuración del origen externo */
+    source: {
+        /** Tipo de origen */
+        provider: string;
+        /** Endpoint o recurso */
+        endpoint?: string;
+    };
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
+}
+/**
+ * Entidad virtual - Orquestación de múltiples fuentes (unified_customers)
+ * Read-only, combina datos de varias entidades
+ */
+interface VirtualEntityDefinition {
+    type: 'virtual';
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
+    labelField: string;
+    /** Definición de campos (esquema unificado) */
+    fields: Record<string, FieldDefinition>;
+    /** Fuentes de datos que se combinan */
+    sources: string[];
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
+}
+/**
+ * Entidad computed - KPIs, estadísticas, métricas calculadas
+ * Read-only, puede cachear opcionalmente
+ */
+interface ComputedEntityDefinition {
+    type: 'computed';
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
+    labelField?: string;
+    /** Definición de campos (estructura del resultado) */
+    fields: Record<string, FieldDefinition>;
+    /** Tiempo de cache en segundos (0 = sin cache) */
+    cacheTtl?: number;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
+/**
+ * Entidad view - Vista optimizada para lectura (projections, denormalizaciones)
+ * Read-only, puede ser vista de BD o virtual
+ */
+interface ViewEntityDefinition {
+    type: 'view';
+    /** Tabla o vista en BD (puede ser VIEW SQL) */
+    table: string;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
+    labelField: string;
+    /** Definición de campos */
+    fields: Record<string, FieldDefinition>;
+    /** Entidad fuente de la que deriva */
+    sourceEntity?: string;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
+}
+/**
+ * Entidad config - Configuración por módulo/tenant
+ * Similar a single pero con scope
+ */
+interface ConfigEntityDefinition extends BaseEntityDefinition {
+    type: 'config';
+    /** Scope de la configuración */
+    scope?: 'global' | 'module' | 'tenant' | 'user';
+    /** Añadir updated_at */
+    timestamps?: boolean;
+    /** Añadir updated_by */
+    audit?: boolean;
+}
+/**
+ * Entidad temporal - Cache, sesiones, OTP codes
+ * Con TTL automático, sin auditoría
+ */
+interface TempEntityDefinition extends BaseEntityDefinition {
+    type: 'temp';
+    /** Tiempo de vida en segundos */
+    ttl: number;
+    /** Campo para mostrar en listas (opcional) */
+    labelField?: string;
+    /** Índices para búsqueda rápida */
+    indexes?: EntityIndex[];
+}
+/**
+ * Union de todas las definiciones de entidad
+ *
+ * | Type       | Persistencia | CRUD            | Uso principal                    |
+ * |------------|--------------|-----------------|----------------------------------|
+ * | collection | Sí (BD)      | Completo        | Datos de negocio (users, posts)  |
+ * | single     | Sí (BD)      | Update/Read     | Config global (site_config)      |
+ * | external   | No           | Read            | Datos externos (stripe_customers)|
+ * | virtual    | No           | Read            | Orquestación (unified_customers) |
+ * | computed   | No/opcional  | Read            | KPIs, estadísticas               |
+ * | view       | Sí/virtual   | Read            | Lectura optimizada (projections) |
+ * | reference  | Sí           | Read (admin)    | Catálogos (countries, currencies)|
+ * | config     | Sí           | Update/Read     | Config por módulo                |
+ * | event      | Sí           | Append          | Auditoría (audit_logs)           |
+ * | temp       | No (TTL)     | Read/Write      | Cache, sesiones (otp_codes)      |
+ * | action     | No           | Execute         | Operaciones, workflows           |
+ */
+type EntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition | ViewEntityDefinition | ReferenceEntityDefinition | ConfigEntityDefinition | EventEntityDefinition | TempEntityDefinition | ActionEntityDefinition;
 /**
  * Requisitos para activar un módulo
  */
@@ -130,19 +555,21 @@ interface ForbiddenErrorInstance {
  * Constructor de ForbiddenError con método from()
  */
 interface ForbiddenErrorConstructor {
-    from: (ability: AbilityLike) => ForbiddenErrorInstance;
+    from: (ability: any) => ForbiddenErrorInstance;
 }
 /**
  * Abilities CASL disponibles en el contexto
  * Permite usar CASL en plugins sin importar @casl/ability directamente
  */
 interface ModuleAbilities {
+    /** Crea una ability CASL para un usuario (acepta argumentos adicionales como permissions) */
+    defineAbilityFor: (user: any, ...args: any[]) => any;
+    /** Empaqueta reglas CASL para enviar al cliente (recibe ability, retorna reglas) */
+    packRules: (ability: any) => unknown[];
     /** Wrapper para verificar permisos contra instancias */
-    subject: (type: string, object: unknown) => unknown;
+    subject: (type: string, object: Record<string, any>) => unknown;
     /** Error de CASL para throwUnlessCan */
     ForbiddenError: ForbiddenErrorConstructor;
-    /** Otros métodos que el backend pueda añadir */
-    [key: string]: unknown;
 }
 /**
  * AuthRequest pre-tipado para uso en plugins
@@ -206,7 +633,8 @@ interface ModuleContext {
     createRouter: () => Router;
     middleware: ModuleMiddlewares;
     registerMiddleware: (name: string, handler: RequestHandler) => void;
-    config: {};
+    /** Configuración resuelta de la aplicación (permite propiedades tipadas del backend) */
+    config: any;
     errors: {
         AppError: new (message: string, statusCode?: number) => Error;
         NotFoundError: new (message?: string) => Error;
@@ -215,10 +643,8 @@ interface ModuleContext {
         ConflictError: new (message?: string) => Error;
     };
     abilities: ModuleAbilities;
-    events: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-        on: (event: string, listener: (...args: unknown[]) => void) => unknown;
-    };
+    /** Sistema de eventos (EventEmitter2 compatible, permite implementaciones tipadas) */
+    events: any;
     mail: {
         send: (options: {
             to: string | string[];
@@ -227,7 +653,7 @@ interface ModuleContext {
             text?: string;
             template?: string;
             data?: Record<string, unknown>;
-        }) => Promise<void>;
+        }) => Promise<unknown>;
     };
     /** Servicios de módulos core (users, etc.) */
     services: CoreServices & Record<string, unknown>;
@@ -264,8 +690,12 @@ interface ModuleManifest {
     routePrefix?: string;
     /** Subjects CASL adicionales (sin entity). Los subjects de entities se infieren automáticamente */
     additionalSubjects?: string[];
-    /** Entidades/tablas del módulo con config CRUD para UI. Sus `name` se registran como subjects CASL */
-    entities?: ModuleEntity[];
+    /**
+     * Definiciones de entidades (nuevo sistema unificado).
+     * Single source of truth para BD, validación, UI y CASL.
+     * Sus subjects se registran automáticamente.
+     */
+    definitions?: EntityDefinition[];
 }
 /**
  * Categorías disponibles para plugins
@@ -293,4 +723,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-export type { AbilityLike, AuthRequest, BaseUser, CoreServices, FieldValidation, ForbiddenErrorConstructor, ForbiddenErrorInstance, FormField, FormFieldType, KnexAlterTableBuilder, KnexCreateTableBuilder, KnexTransaction, ListType, MigrationHelpers, ModuleAbilities, ModuleContext, ModuleEntity, ModuleManifest, ModuleMiddlewares, ModuleRequirements, PaginatedResult, PaginationParams, PluginAuthRequest, PluginCategory, PluginManifest, UsersResolver, ValidateSchemas, ValidationSchema };
+export { type AbilityLike, type ActionEntityDefinition, type AuthRequest, type BaseUser, type CaslAction, type CollectionEntityDefinition, type ComputedEntityDefinition, type ConfigEntityDefinition, type CoreServices, type DbType, type EntityCaslConfig, type EntityDefinition, type EntityIndex, type EventEntityDefinition, type ExternalEntityDefinition, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldValidation, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type FormField, type FormFieldType, type GeneratedPermission, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type ListType, type MigrationHelpers, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PluginAuthRequest, type PluginCategory, type PluginManifest, type ReferenceEntityDefinition, type RolePermission, type SingleEntityDefinition, type TempEntityDefinition, type UsersResolver, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type VirtualEntityDefinition, generateCaslPermissions, generateCaslSeed, generateMigration, generateModel, generateZodSchema, getEntitySubject };

package/dist/index.js

@@ -0,0 +1,451 @@
+// src/generators.ts
+function isPersistentEntity(entity) {
+  const nonPersistent = ["action", "external", "virtual", "computed"];
+  return !nonPersistent.includes(entity.type ?? "collection");
+}
+function generateMigration(entity) {
+  const { table, fields } = entity;
+  const timestamps = "timestamps" in entity ? entity.timestamps : false;
+  const audit = "audit" in entity ? entity.audit : false;
+  const indexes = "indexes" in entity ? entity.indexes : void 0;
+  const lines = [
+    `import type { ModuleContext, Knex } from '@gzl10/nexus-sdk'`,
+    ``,
+    `export async function migrate(ctx: ModuleContext): Promise<void> {`,
+    `  const { db, logger, helpers } = ctx`
+  ];
+  if (timestamps) {
+    lines.push(`  const { addTimestamps } = helpers`);
+  }
+  if (audit) {
+    lines.push(`  const { addAuditFieldsIfMissing } = helpers`);
+  }
+  lines.push(``);
+  lines.push(`  if (!(await db.schema.hasTable('${table}'))) {`);
+  lines.push(`    await db.schema.createTable('${table}', (table: Knex.CreateTableBuilder) => {`);
+  for (const [name, field] of Object.entries(fields)) {
+    const columnCode = generateColumnCode(name, field);
+    lines.push(`      ${columnCode}`);
+  }
+  if (timestamps) {
+    lines.push(`      addTimestamps(table, db)`);
+  }
+  if (indexes?.length) {
+    lines.push(``);
+    for (const idx of indexes) {
+      if (idx.unique) {
+        lines.push(`      table.unique([${idx.columns.map((c) => `'${c}'`).join(", ")}])`);
+      } else {
+        lines.push(`      table.index([${idx.columns.map((c) => `'${c}'`).join(", ")}])`);
+      }
+    }
+  }
+  lines.push(`    })`);
+  lines.push(`    logger.info('Created table: ${table}')`);
+  lines.push(`  }`);
+  if (audit) {
+    lines.push(``);
+    lines.push(`  await addAuditFieldsIfMissing(db, '${table}')`);
+  }
+  lines.push(`}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function generateColumnCode(name, field) {
+  const { db, relation } = field;
+  let code = "";
+  switch (db.type) {
+    case "string":
+      code = db.size ? `table.string('${name}', ${db.size})` : `table.string('${name}')`;
+      break;
+    case "text":
+      code = `table.text('${name}')`;
+      break;
+    case "integer":
+      code = `table.integer('${name}')`;
+      break;
+    case "decimal":
+      if (db.precision) {
+        code = `table.decimal('${name}', ${db.precision[0]}, ${db.precision[1]})`;
+      } else {
+        code = `table.decimal('${name}')`;
+      }
+      break;
+    case "boolean":
+      code = `table.boolean('${name}')`;
+      break;
+    case "date":
+      code = `table.date('${name}')`;
+      break;
+    case "datetime":
+      code = `table.timestamp('${name}')`;
+      break;
+    case "json":
+      code = `table.json('${name}')`;
+      break;
+    case "uuid":
+      code = `table.uuid('${name}')`;
+      break;
+    default:
+      code = `table.string('${name}')`;
+  }
+  if (name === "id") {
+    code += `.primary()`;
+  }
+  if (db.nullable) {
+    code += `.nullable()`;
+  } else {
+    code += `.notNullable()`;
+  }
+  if (db.unique) {
+    code += `.unique()`;
+  }
+  if (db.default !== void 0) {
+    if (typeof db.default === "string") {
+      code += `.defaultTo('${db.default}')`;
+    } else {
+      code += `.defaultTo(${JSON.stringify(db.default)})`;
+    }
+  } else if (db.defaultFn === "now") {
+    code += `.defaultTo(db.fn.now())`;
+  } else if (db.defaultFn === "uuid") {
+    code += `.defaultTo(db.raw('gen_random_uuid()'))`;
+  }
+  if (relation) {
+    const col = relation.column ?? "id";
+    code += `.references('${col}').inTable('${relation.table}')`;
+    if (relation.onDelete) {
+      code += `.onDelete('${relation.onDelete}')`;
+    }
+    if (relation.onUpdate) {
+      code += `.onUpdate('${relation.onUpdate}')`;
+    }
+  }
+  if (db.index && !db.unique && name !== "id") {
+  }
+  return code;
+}
+function generateZodSchema(entity) {
+  const { table, fields } = entity;
+  const entityName = tableToEntityName(table);
+  const lines = [
+    `import { z } from 'zod'`,
+    ``
+  ];
+  lines.push(`// === CREATE ===`);
+  lines.push(`export const create${entityName}Schema = z.object({`);
+  for (const [name, field] of Object.entries(fields)) {
+    if (name === "id" || field.meta?.auditField) continue;
+    const zodCode = generateZodFieldCode(field, "create");
+    if (zodCode) {
+      lines.push(`  ${name}: ${zodCode},`);
+    }
+  }
+  lines.push(`})`);
+  lines.push(``);
+  lines.push(`// === UPDATE ===`);
+  lines.push(`export const update${entityName}Schema = z.object({`);
+  for (const [name, field] of Object.entries(fields)) {
+    if (name === "id" || field.meta?.auditField) continue;
+    const zodCode = generateZodFieldCode(field, "update");
+    if (zodCode) {
+      lines.push(`  ${name}: ${zodCode},`);
+    }
+  }
+  lines.push(`})`);
+  lines.push(``);
+  lines.push(`// === PARAMS ===`);
+  lines.push(`export const ${entityName.toLowerCase()}ParamsSchema = z.object({`);
+  lines.push(`  id: z.string(),`);
+  lines.push(`})`);
+  lines.push(``);
+  lines.push(`// === QUERY ===`);
+  lines.push(`export const ${entityName.toLowerCase()}QuerySchema = z.object({`);
+  lines.push(`  page: z.coerce.number().int().min(1).default(1),`);
+  lines.push(`  limit: z.coerce.number().int().min(1).max(100).default(20),`);
+  for (const [name, field] of Object.entries(fields)) {
+    if (field.meta?.searchable) {
+      const zodType = dbTypeToZodType(field.db.type);
+      lines.push(`  ${name}: ${zodType}.optional(),`);
+    }
+  }
+  lines.push(`})`);
+  lines.push(``);
+  lines.push(`// === INFERRED TYPES ===`);
+  lines.push(`export type Create${entityName}Input = z.infer<typeof create${entityName}Schema>`);
+  lines.push(`export type Update${entityName}Input = z.infer<typeof update${entityName}Schema>`);
+  lines.push(`export type ${entityName}Params = z.infer<typeof ${entityName.toLowerCase()}ParamsSchema>`);
+  lines.push(`export type ${entityName}Query = z.infer<typeof ${entityName.toLowerCase()}QuerySchema>`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function generateZodFieldCode(field, mode) {
+  const { db, validation } = field;
+  let code = dbTypeToZodType(db.type);
+  if (validation) {
+    if (validation.format === "email") {
+      code += `.email()`;
+    } else if (validation.format === "url") {
+      code += `.url()`;
+    } else if (validation.format === "uuid") {
+      code += `.uuid()`;
+    }
+    if (validation.min !== void 0) {
+      if (db.type === "string" || db.type === "text") {
+        code += `.min(${validation.min})`;
+      } else if (db.type === "integer" || db.type === "decimal") {
+        code += `.min(${validation.min})`;
+      }
+    }
+    if (validation.max !== void 0) {
+      if (db.type === "string" || db.type === "text") {
+        code += `.max(${validation.max})`;
+      } else if (db.type === "integer" || db.type === "decimal") {
+        code += `.max(${validation.max})`;
+      }
+    }
+    if (validation.pattern) {
+      code += `.regex(/${validation.pattern}/)`;
+    }
+    if (validation.enum?.length) {
+      code = `z.enum([${validation.enum.map((v) => `'${v}'`).join(", ")}])`;
+    }
+  }
+  if (db.nullable) {
+    code += `.nullable()`;
+  }
+  if (mode === "update") {
+    code += `.optional()`;
+  } else if (mode === "create" && !validation?.required && db.default !== void 0) {
+    code += `.optional()`;
+  }
+  return code;
+}
+function dbTypeToZodType(dbType) {
+  switch (dbType) {
+    case "string":
+    case "text":
+    case "uuid":
+      return "z.string()";
+    case "integer":
+      return "z.number().int()";
+    case "decimal":
+      return "z.number()";
+    case "boolean":
+      return "z.boolean()";
+    case "date":
+    case "datetime":
+      return "z.string().datetime()";
+    case "json":
+      return "z.record(z.unknown())";
+    default:
+      return "z.string()";
+  }
+}
+function generateModel(entity) {
+  const { table, fields } = entity;
+  const timestamps = "timestamps" in entity ? entity.timestamps : false;
+  const audit = "audit" in entity ? entity.audit : false;
+  const entityName = tableToEntityName(table);
+  const lines = [
+    `/**`,
+    ` * ${entity.label}`,
+    ` * Generated from EntityDefinition`,
+    ` */`,
+    `export interface ${entityName} {`
+  ];
+  for (const [name, field] of Object.entries(fields)) {
+    const tsType = dbTypeToTsType(field.db);
+    const optional = field.db.nullable ? "?" : "";
+    lines.push(`  ${name}${optional}: ${tsType}`);
+  }
+  if (timestamps) {
+    lines.push(`  created_at: Date`);
+    lines.push(`  updated_at: Date`);
+  }
+  if (audit) {
+    lines.push(`  created_by: string | null`);
+    lines.push(`  updated_by: string | null`);
+  }
+  lines.push(`}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function dbTypeToTsType(db) {
+  switch (db.type) {
+    case "string":
+    case "text":
+    case "uuid":
+      return "string";
+    case "integer":
+    case "decimal":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "date":
+    case "datetime":
+      return "Date";
+    case "json":
+      return "Record<string, unknown>";
+    default:
+      return "unknown";
+  }
+}
+function tableToEntityName(table) {
+  const withoutPrefix = table.replace(/^[a-z]{2,4}_/, "");
+  const singular = withoutPrefix.endsWith("ies") ? withoutPrefix.slice(0, -3) + "y" : withoutPrefix.endsWith("s") ? withoutPrefix.slice(0, -1) : withoutPrefix;
+  return singular.charAt(0).toUpperCase() + singular.slice(1);
+}
+function tableToSubject(table) {
+  const match = table.match(/^([a-z]{2,4})_(.+)$/);
+  if (!match) return tableToEntityName(table);
+  const [, prefix, rest] = match;
+  const prefixPascal = prefix.charAt(0).toUpperCase() + prefix.slice(1);
+  const singular = rest.endsWith("ies") ? rest.slice(0, -3) + "y" : rest.endsWith("s") ? rest.slice(0, -1) : rest;
+  const restPascal = singular.charAt(0).toUpperCase() + singular.slice(1);
+  return prefixPascal + restPascal;
+}
+function getFieldsForRole(entity, role, action) {
+  const { fields, casl } = entity;
+  const isReadAction = action === "read";
+  const isWriteAction = action === "create" || action === "update";
+  if (action === "manage") return null;
+  const allowedFields = [];
+  const sensitiveFields = casl?.sensitiveFields ?? [];
+  for (const [fieldName, field] of Object.entries(fields)) {
+    const fieldCasl = field.meta?.casl;
+    if (sensitiveFields.includes(fieldName) && role !== "ADMIN") {
+      continue;
+    }
+    if (isReadAction) {
+      if (fieldCasl?.readRoles !== void 0) {
+        if (fieldCasl.readRoles.length === 0 || fieldCasl.readRoles.includes(role)) {
+          allowedFields.push(fieldName);
+        }
+      } else {
+        allowedFields.push(fieldName);
+      }
+    } else if (isWriteAction) {
+      if (fieldCasl?.writeRoles !== void 0) {
+        if (fieldCasl.writeRoles.length === 0 || fieldCasl.writeRoles.includes(role)) {
+          allowedFields.push(fieldName);
+        }
+      } else {
+        allowedFields.push(fieldName);
+      }
+    } else {
+      return null;
+    }
+  }
+  const allFieldNames = Object.keys(fields).filter((f) => !sensitiveFields.includes(f) || role === "ADMIN");
+  if (allowedFields.length === allFieldNames.length) {
+    return null;
+  }
+  return allowedFields.length > 0 ? allowedFields : null;
+}
+function generateCaslPermissions(entity) {
+  const { table, fields, casl } = entity;
+  if (!casl) return [];
+  const subject = casl.subject ?? tableToSubject(table);
+  const permissions = [];
+  for (const [role, config] of Object.entries(casl.permissions ?? {})) {
+    for (const action of config.actions) {
+      let conditions = config.conditions ?? null;
+      if (casl.ownership && (action === "update" || action === "delete") && !conditions) {
+        const userField = casl.ownership.userField ?? "id";
+        conditions = { [casl.ownership.field]: `\${user.${userField}}` };
+      }
+      let permFields = config.fields ?? null;
+      if (!permFields) {
+        permFields = getFieldsForRole(entity, role, action);
+      }
+      permissions.push({
+        role,
+        action,
+        subject,
+        conditions: conditions ? JSON.stringify(conditions) : null,
+        fields: permFields ? JSON.stringify(permFields) : null,
+        inverted: config.inverted ?? false
+      });
+    }
+  }
+  return permissions;
+}
+function generateCaslSeed(entities) {
+  const allPermissions = [];
+  for (const entity of entities) {
+    if (isPersistentEntity(entity)) {
+      allPermissions.push(...generateCaslPermissions(entity));
+    }
+  }
+  if (allPermissions.length === 0) {
+    return "// No CASL permissions defined in entities\n";
+  }
+  const lines = [
+    `import type { ModuleContext } from '@gzl10/nexus-sdk'`,
+    ``,
+    `/**`,
+    ` * Seed de permisos CASL generado desde EntityDefinition`,
+    ` */`,
+    `export async function seedPermissions(ctx: ModuleContext): Promise<void> {`,
+    `  const { db, generateId, logger } = ctx`,
+    ``,
+    `  // Obtener IDs de roles`,
+    `  const roles = await db('rol_roles').select('id', 'name')`,
+    `  const roleMap = Object.fromEntries(roles.map((r: { id: string; name: string }) => [r.name, r.id]))`,
+    ``,
+    `  const permissions = [`
+  ];
+  for (const perm of allPermissions) {
+    lines.push(`    {`);
+    lines.push(`      role: '${perm.role}',`);
+    lines.push(`      action: '${perm.action}',`);
+    lines.push(`      subject: '${perm.subject}',`);
+    lines.push(`      conditions: ${perm.conditions ? `'${perm.conditions}'` : "null"},`);
+    lines.push(`      fields: ${perm.fields ? `'${perm.fields}'` : "null"},`);
+    lines.push(`      inverted: ${perm.inverted}`);
+    lines.push(`    },`);
+  }
+  lines.push(`  ]`);
+  lines.push(``);
+  lines.push(`  for (const perm of permissions) {`);
+  lines.push(`    const roleId = roleMap[perm.role]`);
+  lines.push(`    if (!roleId) {`);
+  lines.push(`      logger.warn({ role: perm.role }, 'Role not found, skipping permission')`);
+  lines.push(`      continue`);
+  lines.push(`    }`);
+  lines.push(``);
+  lines.push(`    // Check if permission exists`);
+  lines.push(`    const existing = await db('rol_role_permissions')`);
+  lines.push(`      .where({ role_id: roleId, action: perm.action, subject: perm.subject })`);
+  lines.push(`      .first()`);
+  lines.push(``);
+  lines.push(`    if (!existing) {`);
+  lines.push(`      await db('rol_role_permissions').insert({`);
+  lines.push(`        id: generateId(),`);
+  lines.push(`        role_id: roleId,`);
+  lines.push(`        action: perm.action,`);
+  lines.push(`        subject: perm.subject,`);
+  lines.push(`        conditions: perm.conditions,`);
+  lines.push(`        fields: perm.fields,`);
+  lines.push(`        inverted: perm.inverted`);
+  lines.push(`      })`);
+  lines.push(`    }`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  logger.info('Seeded CASL permissions from EntityDefinitions')`);
+  lines.push(`}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function getEntitySubject(entity) {
+  return entity.casl?.subject ?? tableToSubject(entity.table);
+}
+export {
+  generateCaslPermissions,
+  generateCaslSeed,
+  generateMigration,
+  generateModel,
+  generateZodSchema,
+  getEntitySubject
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gzl10/nexus-sdk",
-  "version": "0.1.11",
+  "version": "0.3.0",
   "description": "SDK types for creating Nexus plugins and modules",
   "type": "module",
   "main": "./dist/index.js",