@gzl10/nexus-sdk 0.4.0 → 0.5.0

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import {
+  GENERATED_DIR,
+  generateCaslSeed,
+  generateMigrationsFile,
+  generateModelsFile,
+  generateSchemasFile
+} from "../chunk-XEPNN6IG.js";
+
+// src/cli/index.ts
+import { Command as Command2 } from "commander";
+
+// src/cli/commands/generate.ts
+import { Command } from "commander";
+import { join, dirname } from "path";
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import pc from "picocolors";
+import { watch } from "chokidar";
+
+// src/cli/discovery/module-finder.ts
+import fg from "fast-glob";
+async function findModules(opts) {
+  const pattern = opts.module ? `**/${opts.module}/index.ts` : "**/index.ts";
+  const files = await fg(pattern, {
+    cwd: opts.path,
+    absolute: true,
+    ignore: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/__generated__/**",
+      "index.ts"
+      // Exclude root modules/index.ts (not nested ones)
+    ]
+  });
+  return files.filter((file) => {
+    const parts = file.split("/");
+    const fileName = parts.pop();
+    const folderName = parts.pop();
+    return fileName === "index.ts" && folderName && !folderName.startsWith("_");
+  });
+}
+
+// src/cli/discovery/manifest-extractor.ts
+import { createJiti } from "jiti";
+var jiti = createJiti(import.meta.url, {
+  interopDefault: true,
+  moduleCache: false
+  // Don't cache for watch mode
+});
+function isModuleManifest(value) {
+  return typeof value === "object" && value !== null && "name" in value && typeof value.name === "string";
+}
+async function extractManifest(modulePath, verbose = false) {
+  try {
+    const mod = await jiti.import(modulePath);
+    for (const value of Object.values(mod)) {
+      if (isModuleManifest(value)) {
+        const manifest = value;
+        if (manifest.definitions?.length) {
+          return {
+            path: modulePath,
+            manifest,
+            definitions: manifest.definitions
+          };
+        }
+      }
+    }
+    return null;
+  } catch (error) {
+    if (verbose) {
+      console.error(`Error loading ${modulePath}: ${getErrorMessage(error)}`);
+    }
+    return null;
+  }
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+// src/cli/commands/generate.ts
+async function runGenerate(opts) {
+  const startTime = Date.now();
+  console.log(pc.blue("Nexus SDK Generator"));
+  console.log(pc.dim(`Scanning ${opts.path}...
+`));
+  const modulePaths = await findModules({ path: opts.path, module: opts.module });
+  if (opts.verbose) {
+    console.log(pc.dim(`Found ${modulePaths.length} potential module(s)`));
+  }
+  if (modulePaths.length === 0) {
+    console.log(pc.yellow("No modules found"));
+    return;
+  }
+  const modules = [];
+  for (const path of modulePaths) {
+    const extracted = await extractManifest(path, opts.verbose);
+    if (extracted) {
+      modules.push(extracted);
+      if (opts.verbose) {
+        console.log(pc.dim(`  \u2713 ${extracted.manifest.name}: ${extracted.definitions.length} entities`));
+      }
+    }
+  }
+  if (modules.length === 0) {
+    console.log(pc.yellow("No modules with definitions found"));
+    return;
+  }
+  let totalFiles = 0;
+  for (const mod of modules) {
+    const moduleDir = dirname(mod.path);
+    const outputDir = join(moduleDir, opts.output || GENERATED_DIR);
+    if (!opts.dryRun && !existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+    const files = [];
+    if (!opts.skipSchemas) {
+      const content = generateSchemasFile(mod.definitions);
+      const filePath = join(outputDir, `${mod.manifest.name}.schemas.ts`);
+      if (!opts.dryRun) writeFileSync(filePath, content);
+      files.push("schemas");
+    }
+    if (!opts.skipModels) {
+      const content = generateModelsFile(mod.definitions);
+      const filePath = join(outputDir, `${mod.manifest.name}.models.ts`);
+      if (!opts.dryRun) writeFileSync(filePath, content);
+      files.push("models");
+    }
+    if (!opts.skipMigrations) {
+      const content = generateMigrationsFile(mod.definitions);
+      const filePath = join(outputDir, `${mod.manifest.name}.migrate.ts`);
+      if (!opts.dryRun) writeFileSync(filePath, content);
+      files.push("migrate");
+    }
+    if (!opts.skipCasl) {
+      const content = generateCaslSeed(mod.definitions);
+      const filePath = join(outputDir, `${mod.manifest.name}.casl.ts`);
+      if (!opts.dryRun) writeFileSync(filePath, content);
+      files.push("casl");
+    }
+    totalFiles += files.length;
+    const prefix = opts.dryRun ? pc.yellow("[dry-run]") : pc.green("\u2713");
+    console.log(`${prefix} ${pc.bold(mod.manifest.name)}: ${files.join(", ")}`);
+  }
+  const elapsed = Date.now() - startTime;
+  console.log(
+    `
+${pc.green("\u2728")} Generated ${totalFiles} files in ${modules.length} module(s) (${elapsed}ms)`
+  );
+}
+function createGenerateCommand() {
+  return new Command("generate").description("Generate code from EntityDefinitions").option("-p, --path <dir>", "Base modules directory", "src/modules").option("-m, --module <name>", "Generate only specific module").option("-o, --output <dir>", "Output directory name", "__generated__").option("-w, --watch", "Watch for changes and regenerate").option("--dry-run", "Show what would be generated").option("--skip-schemas", "Skip .schemas.ts generation").option("--skip-models", "Skip .models.ts generation").option("--skip-migrations", "Skip .migrate.ts generation").option("--skip-casl", "Skip .casl.ts generation").option("--verbose", "Show detailed logs").action(async (opts) => {
+    await runGenerate(opts);
+    if (opts.watch) {
+      console.log(pc.blue("\nWatching for changes..."));
+      const watcher = watch(["**/*.entity.ts", "**/index.ts"], {
+        cwd: opts.path,
+        ignored: ["**/node_modules/**", "**/__generated__/**", "**/dist/**"],
+        ignoreInitial: true
+      });
+      watcher.on("change", async (path) => {
+        console.log(pc.dim(`
+Change detected: ${path}`));
+        await runGenerate({ ...opts, watch: false });
+      });
+      watcher.on("add", async (path) => {
+        console.log(pc.dim(`
+New file: ${path}`));
+        await runGenerate({ ...opts, watch: false });
+      });
+    }
+  });
+}
+
+// src/cli/index.ts
+var program = new Command2().name("nexus-sdk").description("Nexus SDK CLI - Code generation from EntityDefinitions").version("0.5.0");
+program.addCommand(createGenerateCommand());
+program.parse();

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Knex } from 'knex';
 export { Knex } from 'knex';
-import { Request, RequestHandler, Router } from 'express';
+import { Request, Router, RequestHandler } from 'express';
 export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router } from 'express';
 import { Logger } from 'pino';
 
@@ -11,6 +11,8 @@ import { Logger } from 'pino';
  * que pueden ser escritos a archivos o usados en runtime.
  */
 
+/** Directorio estándar para código generado */
+declare const GENERATED_DIR = "__generated__";
 /**
  * Entidades que persisten en BD local con tabla propia
  * Excluye: action, external, virtual, computed, single (usa tabla compartida)
@@ -130,6 +132,15 @@ declare function generateSchemasFile(definitions: EntityDefinition[]): string;
  * writeFileSync('users.models.ts', code)
  */
 declare function generateModelsFile(definitions: EntityDefinition[]): string;
+/**
+ * Genera archivo completo de migración Knex para múltiples entidades
+ * Consolida todas las entidades de un módulo en un solo archivo de migración
+ *
+ * @example
+ * const code = generateMigrationsFile([userEntity, roleEntity])
+ * writeFileSync('users.migrate.ts', code)
+ */
+declare function generateMigrationsFile(definitions: EntityDefinition[]): string;
 
 /**
  * @gzl10/nexus-sdk
@@ -416,6 +427,8 @@ interface CollectionEntityDefinition extends BaseEntityDefinition {
     audit?: boolean;
     /** Índices compuestos */
     indexes?: EntityIndex[];
+    /** Usar deleted_at en vez de DELETE físico */
+    softDelete?: boolean;
 }
 /**
  * Entidad singleton - Un solo registro en tabla compartida sys_settings
@@ -434,6 +447,8 @@ interface SingleEntityDefinition {
     label: string;
     /** Definición de campos (estructura del JSON value) */
     fields: Record<string, FieldDefinition>;
+    /** Valores por defecto al crear */
+    defaults?: Record<string, unknown>;
     /** Autorización CASL */
     casl?: EntityCaslConfig;
 }
@@ -448,6 +463,10 @@ interface ReferenceEntityDefinition extends BaseEntityDefinition {
     timestamps?: boolean;
     /** Índices compuestos */
     indexes?: EntityIndex[];
+    /** Datos iniciales para seed */
+    seed?: Array<Record<string, unknown>>;
+    /** Permitir CRUD para admin (default: false, solo lectura) */
+    allowAdminEdit?: boolean;
 }
 /**
  * Entidad de eventos - Logs de auditoría, append-only
@@ -458,6 +477,13 @@ interface EventEntityDefinition extends BaseEntityDefinition {
     labelField: string;
     /** Siempre true para eventos */
     timestamps: true;
+    /** Política de retención automática */
+    retention?: {
+        /** Eliminar registros más antiguos que N días */
+        days?: number;
+        /** Mantener solo los últimos N registros */
+        maxRows?: number;
+    };
 }
 /**
  * Entidad de acción - Comandos/operaciones sin persistencia
@@ -466,8 +492,16 @@ interface ActionEntityDefinition {
     type: 'action';
     /** Nombre para mostrar en UI */
     label: string;
-    /** Solo campos de formulario, sin BD */
+    /** 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>;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
 /**
  * Entidad externa - Datos de APIs externas (stripe_customers, github_repos)
@@ -481,12 +515,21 @@ interface ExternalEntityDefinition {
     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 */
+    /** Nombre del adapter registrado (ej: 'stripe', 'github') */
+    adapter: string;
+    /** Configuración del origen externo (pasada al adapter) */
+    source?: {
+        /** Endpoint o recurso específico */
         endpoint?: string;
+        /** Config adicional */
+        [key: string]: unknown;
+    };
+    /** Configuración de cache */
+    cache?: {
+        /** TTL en segundos */
+        ttl: number;
+        /** Campo para generar cache key */
+        key?: string;
     };
     /** Autorización CASL */
     casl?: EntityCaslConfig;
@@ -503,8 +546,10 @@ interface VirtualEntityDefinition {
     labelField: string;
     /** Definición de campos (esquema unificado) */
     fields: Record<string, FieldDefinition>;
-    /** Fuentes de datos que se combinan */
+    /** Fuentes de datos que se combinan (nombres de entidades/tables) */
     sources: string[];
+    /** Función que combina los datos de las fuentes */
+    resolver?: (sources: Record<string, unknown[]>, ctx: ModuleContext) => unknown[] | Promise<unknown[]>;
     /** Autorización CASL */
     casl?: EntityCaslConfig;
 }
@@ -520,8 +565,13 @@ interface ComputedEntityDefinition {
     labelField?: string;
     /** Definición de campos (estructura del resultado) */
     fields: Record<string, FieldDefinition>;
-    /** Tiempo de cache en segundos (0 = sin cache) */
-    cacheTtl?: number;
+    /** Función que calcula los datos */
+    compute?: (ctx: ModuleContext, params?: Record<string, unknown>) => Promise<unknown[]>;
+    /** Configuración de cache */
+    cache?: {
+        /** TTL en segundos (0 = sin cache) */
+        ttl: number;
+    };
     /** Autorización CASL */
     casl?: EntityCaslConfig;
 }
@@ -541,6 +591,8 @@ interface ViewEntityDefinition {
     fields: Record<string, FieldDefinition>;
     /** Entidad fuente de la que deriva */
     sourceEntity?: string;
+    /** Query SQL o builder para crear la vista */
+    query?: string | ((db: Knex) => Knex.QueryBuilder);
     /** Autorización CASL */
     casl?: EntityCaslConfig;
 }
@@ -550,8 +602,12 @@ interface ViewEntityDefinition {
  */
 interface ConfigEntityDefinition extends BaseEntityDefinition {
     type: 'config';
+    /** Campo que identifica el scope (ej: 'module_name', 'tenant_id') */
+    scopeField?: string;
     /** Scope de la configuración */
     scope?: 'global' | 'module' | 'tenant' | 'user';
+    /** Valores por defecto */
+    defaults?: Record<string, unknown>;
     /** Añadir updated_at */
     timestamps?: boolean;
     /** Añadir updated_by */
@@ -565,11 +621,17 @@ interface TempEntityDefinition extends BaseEntityDefinition {
     type: 'temp';
     /** Tiempo de vida en segundos */
     ttl: number;
+    /** Campo que almacena la fecha de expiración (default: 'expires_at') */
+    ttlField?: string;
     /** Campo para mostrar en listas (opcional) */
     labelField?: string;
     /** Índices para búsqueda rápida */
     indexes?: EntityIndex[];
 }
+/**
+ * Todos los tipos de entidad disponibles
+ */
+type EntityType = 'collection' | 'single' | 'external' | 'virtual' | 'computed' | 'view' | 'reference' | 'config' | 'event' | 'temp' | 'action';
 /**
  * Union de todas las definiciones de entidad
  *
@@ -634,21 +696,6 @@ interface ModuleAbilities {
  * Usa BaseUser y AbilityLike para tipado básico sin depender del backend
  */
 type PluginAuthRequest = AuthRequest<BaseUser, AbilityLike>;
-/**
- * Resolver de usuarios para plugins
- * Permite acceder a usuarios sin conocer la implementación interna
- */
-interface UsersResolver {
-    findById: (id: string) => Promise<BaseUser | null>;
-    findByIds: (ids: string[]) => Promise<BaseUser[]>;
-}
-/**
- * Servicios core inyectados por el backend
- * Los plugins acceden a estos servicios via ctx.services
- */
-interface CoreServices {
-    users?: UsersResolver;
-}
 /**
  * Helpers para migraciones de base de datos
  */
@@ -713,8 +760,8 @@ interface ModuleContext {
             data?: Record<string, unknown>;
         }) => Promise<unknown>;
     };
-    /** Servicios de módulos core (users, etc.) */
-    services: CoreServices & Record<string, unknown>;
+    /** Servicios de módulos (inyectados por backend) */
+    services: Record<string, unknown>;
 }
 /**
  * Manifest de un módulo Nexus
@@ -722,8 +769,6 @@ interface ModuleContext {
 interface ModuleManifest {
     /** Identificador único del módulo (ej: 'users', 'posts') */
     name: string;
-    /** Código único del módulo (ej: 'USR', 'PST'). Opcional si pertenece a un plugin */
-    code?: string;
     /** Nombre para mostrar en UI. Opcional si pertenece a un plugin */
     label?: string;
     /** Icono del módulo (Iconify MDI: 'mdi:account-group') */
@@ -736,7 +781,7 @@ interface ModuleManifest {
     dependencies?: string[];
     /** Requisitos para activar el módulo */
     required?: ModuleRequirements;
-    /** Función de migración de base de datos */
+    /** Función de migración de base de datos. Normalmente se genera desde definitions (EntityDefinition) */
     migrate?: (ctx: ModuleContext) => Promise<void>;
     /** Función de seed de datos iniciales */
     seed?: (ctx: ModuleContext) => Promise<void>;
@@ -781,4 +826,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-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 NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, 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, generateModelsFile, generateReadOnlyModel, generateReadOnlySchema, generateSchemasFile, generateZodSchema, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };
+export { type AbilityLike, type ActionEntityDefinition, type AuthRequest, type BaseUser, type CaslAction, type CollectionEntityDefinition, type ComputedEntityDefinition, type ConfigEntityDefinition, type DbType, type EntityCaslConfig, type EntityDefinition, type EntityIndex, type EntityType, 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, GENERATED_DIR, 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 NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginCategory, type PluginManifest, type ReferenceEntityDefinition, type RolePermission, type SingleEntityDefinition, type TempEntityDefinition, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type VirtualEntityDefinition, generateCaslPermissions, generateCaslSeed, generateMigration, generateMigrationsFile, generateModel, generateModelsFile, generateReadOnlyModel, generateReadOnlySchema, generateSchemasFile, generateZodSchema, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };