blackcoffee2 2.1.0

package/docs/APP_HOOKS_HANDLER.md

@@ -0,0 +1,432 @@
+# App Hooks Handler - Documentación Técnica
+
+## 📋 Descripción General
+
+Este documento explica la función y carga del sistema de hooks para aplicaciones en BlackCoffee App Server.
+
+---
+
+## 🗂️ Archivos Relacionados
+
+En BlackCoffee existen **DOS** archivos relacionados con los hooks de aplicaciones:
+
+### 1. `includes/appHooks.js` - EL QUE SE USA ACTUALMENTE
+
+**Ubicación:** `/home/bds/blackcoffeeRC/includes/appHooks.js`
+
+**Estado:** ✅ Activo y en uso
+
+**Función:** Registrar los 13 hooks para el ciclo de vida de aplicaciones.
+
+### 2. `app-hooks-handler.js` - Handler Oficial de Insitu
+
+**Ubicación:** `node_modules/insitu-js/lib/core/hooks-handlers/app-hooks-handler.js`
+
+**Estado:** ❌ Creado pero NO usado aún
+
+**Función:** Centralizar el manejo de hooks de aplicaciones en Insitu Framework.
+
+---
+
+## 🔧 `includes/appHooks.js` - Implementación Actual
+
+### Función Principal
+
+Registrar todos los hooks necesarios para la gestión de aplicaciones en BlackCoffee App Server.
+
+### Los 13 Hooks Registrados
+
+#### 1. Application Lifecycle (6 hooks)
+
+```javascript
+hooks.addAction('app_deploying', (manifest, tempPath) => {
+  console.log(`📦 [APP] Desplegando ${manifest.name} v${manifest.version}`);
+});
+
+hooks.addAction('app_deployed', (manifest, tempPath, deployedPath) => {
+  console.log(`✅ [APP] ${manifest.name} v${manifest.version} desplegado en ${deployedPath}`);
+});
+
+hooks.addAction('app_undeploying', (appName, version) => {
+  console.log(`🗑️  [APP] Removiendo ${appName} v${version}`);
+});
+
+hooks.addAction('app_undeployed', (appName, version, removedPath) => {
+  console.log(`❌ [APP] ${appName} v${version} removido de ${removedPath}`);
+});
+
+hooks.addAction('app_starting', (appName, version) => {
+  console.log(`▶️  [APP] Iniciando ${appName} v${version}`);
+});
+
+hooks.addAction('app_started', (appName, version) => {
+  console.log(`✅ [APP] ${appName} v${version} iniciada correctamente`);
+});
+
+hooks.addAction('app_stopping', (appName, version) => {
+  console.log(`⏹️  [APP] Deteniendo ${appName} v${version}`);
+});
+
+hooks.addAction('app_stopped', (appName, version) => {
+  console.log(`⏹️  [APP] ${appName} v${version} detenida`);
+});
+
+hooks.addAction('app_restarting', (appName, version) => {
+  console.log(`🔄 [APP] Reiniciando ${appName} v${version}`);
+});
+
+hooks.addAction('app_restarted', (appName, version) => {
+  console.log(`✅ [APP] ${appName} v${version} reiniciada`);
+});
+```
+
+#### 2. Manifest Validation (2 hooks)
+
+```javascript
+hooks.addFilter('app_manifest_validating', (isValid, manifest, errors) => {
+  // Validaciones obligatorias básicas
+  const requiredFields = ['name', 'version'];
+  
+  for (const field of requiredFields) {
+    if (!manifest[field]) {
+      errors.push(`Campo requerido faltante: ${field}`);
+      return false;
+    }
+  }
+  
+  // Validar que name sea un string válido para URL
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(manifest.name)) {
+    errors.push('El nombre de la app debe ser alfanumérico (minúsculas)');
+    return false;
+  }
+  
+  return isValid;
+}, 10);
+
+hooks.addAction('app_manifest_validated', (manifest, isValid, errors) => {
+  if (!isValid) {
+    console.error(`❌ [MANIFEST] ${manifest.name}: ${errors.join(', ')}`);
+  } else {
+    console.log(`✅ [MANIFEST] ${manifest.name} v${manifest.version} validado correctamente`);
+  }
+});
+```
+
+#### 3. Route Registration (2 hooks)
+
+```javascript
+hooks.addFilter('before_app_routes_register', (routeConfig, appName, version) => {
+  // Validar que appName y version sean strings válidos
+  if (!appName || appName === 'unknown' || !version || version === 'unknown') {
+    console.warn(`[HOOK] Warning: appName o version no válidos`);
+    return routeConfig;
+  }
+  
+  // Obtener prefijo del manifest o generar automático
+  const prefix = `/${appName}/${version}`;
+  
+  // Evitar doble prefijo
+  if (!routeConfig.path.startsWith(prefix)) {
+    routeConfig.path = `${prefix}${routeConfig.path}`;
+  }
+  
+  // Agregar metadata de la app a la ruta
+  routeConfig.app = {
+    name: appName,
+    version: version,
+    deployedAt: new Date().toISOString()
+  };
+  
+  return routeConfig;
+}, 10, 3); // priority=10, acceptedArgs=3
+
+hooks.addAction('after_app_routes_register', (routes, appName, version) => {
+  console.log(`📍 [ROUTES] ${routes.length} rutas registradas para ${appName} v${version}`);
+});
+```
+
+#### 4. Dependency Management (2 hooks)
+
+```javascript
+hooks.addAction('app_dependencies_checking', (dependencies, appName, version) => {
+  if (dependencies && Object.keys(dependencies).length > 0) {
+    console.log(`📦 [DEPS] Verificando dependencias para ${appName} v${version}`);
+  }
+});
+
+hooks.addAction('app_dependencies_installed', (appName, version, success) => {
+  if (success) {
+    console.log(`✅ [DEPS] Dependencias instaladas para ${appName} v${version}`);
+  } else {
+    console.warn(`⚠️  [DEPS] Error instalando dependencias para ${appName} v${version}`);
+  }
+});
+```
+
+#### 5. Configuration (2 hooks)
+
+```javascript
+hooks.addFilter('app_config_loading', (config, appName, version) => {
+  // Aquí se puede fusionar con configuración global si existe
+  return config;
+}, 10);
+
+hooks.addAction('app_config_loaded', (config, appName, version) => {
+  console.log(`⚙️  [CONFIG] Configuración cargada para ${appName} v${version}`);
+});
+```
+
+---
+
+## 📥 ¿Cómo se Carga en BlackCoffee?
+
+### Archivo: `server.js`
+
+#### Paso 1: Import (Línea 13)
+
+```javascript
+const { registerAppHooks } = require('./includes/appHooks');
+```
+
+#### Paso 2: Registro (Líneas 50-53)
+
+```javascript
+// Crear instancia del servidor
+const server = new APIServer(config);
+
+// Registrar hooks de App Server
+registerAppHooks(server.hooks);
+
+// Inicializar AppLoader y exponer globalmente
+const appLoader = new AppLoader(server);
+global.appLoader = appLoader;
+server.appLoader = appLoader;
+
+console.log('📦 AppLoader inicializado\n');
+```
+
+---
+
+## 🔄 Flujo de Carga Completo
+
+```
+1. server.js se ejecuta
+   ↓
+2. Importa registerAppHooks desde includes/appHooks.js
+   ↓
+3. Crea instancia de APIServer (Insitu Framework)
+   ↓
+4. Llama registerAppHooks(server.hooks)
+   ↓
+5. registerAppHooks registra los 13 hooks en el HookSystem de Insitu
+   ↓
+6. Hooks quedan disponibles para todo el servidor
+   ↓
+7. appLoader.js usa los hooks cuando carga aplicaciones:
+   - hooks.applyFilters('before_app_routes_register', ...)
+   - hooks.doAction('after_app_routes_register', ...)
+   - hooks.doAction('app_deploying', ...)
+   - hooks.doAction('app_manifest_validated', ...)
+   - etc.
+```
+
+---
+
+## 📊 Ejemplo de Uso en appLoader.js
+
+### Archivo: `core/appLoader.js`
+
+```javascript
+async loadAppRoutes(routesPath, appName, version) {
+  const hooks = this.hooks;
+  const appPath = path.join(this.appsDir, appName, version);
+  
+  try {
+    let routesData = fs.readFileSync(routesPath, 'utf8');
+    
+    // Reemplazar __APP_DIR__ con la ruta real de la aplicación
+    routesData = routesData.replace(/__APP_DIR__/g, appPath);
+    
+    const routes = JSON.parse(routesData);
+    
+    if (!Array.isArray(routes)) {
+      throw new Error('El archivo de rutas debe contener un array');
+    }
+    
+    console.log(`📍 Cargando ${routes.length} rutas para ${appName} v${version}...`);
+    
+    for (const route of routes) {
+      // Crear ruta modificada con prefijo
+      const modifiedRoute = { ...route };
+      const prefix = `/${appName}/${version}`;
+      
+      // Evitar doble prefijo
+      if (!modifiedRoute.path.startsWith(prefix)) {
+        modifiedRoute.path = `${prefix}${modifiedRoute.path}`;
+      }
+      
+      // Agregar metadata de la app a la ruta
+      modifiedRoute.app = {
+        name: appName,
+        version: version,
+        deployedAt: new Date().toISOString()
+      };
+      
+      // Disparar hook filter para permitir modificaciones adicionales
+      // applyFilters(hookName, value, ...additionalArgs)
+      // acceptedArgs debe ser 3 (routeConfig, appName, version)
+      const finalRoute = hooks.applyFilters(
+        'before_app_routes_register',
+        modifiedRoute,
+        appName,
+        version
+      );
+      
+      console.log(`   Registrando: ${finalRoute.method} ${finalRoute.path}`);
+      
+      // Registrar ruta en el servidor
+      this.server.addRoute(finalRoute);
+    }
+    
+    // Disparar hook after_app_routes_register
+    hooks.doAction('after_app_routes_register', routes, appName, version);
+    
+  } catch (error) {
+    console.error(`❌ Error cargando rutas: ${error.message}`);
+    throw error;
+  }
+}
+```
+
+---
+
+## 🆚 Comparación: appHooks.js vs app-hooks-handler.js
+
+| Aspecto | `includes/appHooks.js` | `app-hooks-handler.js` (Insitu) |
+|---------|----------------------|--------------------------------|
+| **Ubicación** | BlackCoffee local | Insitu Framework |
+| **Estado** | ✅ Activo y en uso | ❌ Creado pero NO usado |
+| **Propósito** | Registrar hooks específicos | Centralizar handlers |
+| **Carga** | `server.js` línea 13 | No importado |
+| **Hooks** | 13 hooks registrados | 3 métodos handler |
+| **Dependencia** | Ninguna | Requiere Insitu v1.2.1+ |
+
+---
+
+## 🎯 Handler Oficial de Insitu (NO USADO)
+
+### Archivo: `node_modules/insitu-js/lib/core/hooks-handlers/app-hooks-handler.js`
+
+### Métodos Disponibles
+
+```javascript
+class AppHooksHandler {
+  /**
+   * Dispara el hook antes de registrar las rutas de una aplicación
+   */
+  static handleBeforeAppRouteRegister(server, routeConfig, appName, version) {
+    if (server.hooks) {
+      return server.hooks.applyFilters(
+        'before_app_routes_register',
+        routeConfig,
+        appName,
+        version
+      );
+    }
+    return routeConfig;
+  }
+
+  /**
+   * Dispara el hook después de registrar las rutas de una aplicación
+   */
+  static handleAfterAppRoutesRegister(server, routes, appName, version) {
+    if (server.hooks) {
+      server.hooks.doAction('after_app_routes_register', routes, appName, version);
+    }
+  }
+
+  /**
+   * Dispara el hook cuando una ruta de aplicación es registrada
+   */
+  static handleAppRouteRegistered(server, route, appName, version) {
+    if (server.hooks) {
+      server.hooks.doAction('app_route_registered', route, appName, version);
+    }
+  }
+}
+
+module.exports = AppHooksHandler;
+```
+
+### ¿Cómo Integrarlo en el Futuro?
+
+**Paso 1:** Importar en `server.js`
+
+```javascript
+const AppHooksHandler = require('insitu-js/lib/core/hooks-handlers/app-hooks-handler');
+```
+
+**Paso 2:** Usar en `core/appLoader.js`
+
+```javascript
+const AppHooksHandler = require('insitu-js/lib/core/hooks-handlers/app-hooks-handler');
+
+// Reemplazar:
+const finalRoute = hooks.applyFilters('before_app_routes_register', ...);
+
+// Por:
+const finalRoute = AppHooksHandler.handleBeforeAppRouteRegister(
+  this.server,
+  modifiedRoute,
+  appName,
+  version
+);
+
+// Y:
+hooks.doAction('after_app_routes_register', routes, appName, version);
+
+// Por:
+AppHooksHandler.handleAfterAppRoutesRegister(
+  this.server,
+  routes,
+  appName,
+  version
+);
+```
+
+**Paso 3:** Mantener `includes/appHooks.js` para hooks específicos de BlackCoffee que Insitu no tiene.
+
+---
+
+## 📝 Resumen
+
+### Estado Actual
+
+- ✅ `includes/appHooks.js` - **SE USA** - Registra 13 hooks en BlackCoffee
+- ❌ `app-hooks-handler.js` (Insitu) - **NO SE USA** - Handler oficial creado pero no integrado
+
+### Carga Actual
+
+```javascript
+// server.js línea 13
+const { registerAppHooks } = require('./includes/appHooks');
+
+// server.js línea 50
+registerAppHooks(server.hooks);
+```
+
+### Hooks en Uso
+
+1. **Application Lifecycle:** 6 hooks (deploy, undeploy, start, stop, restart)
+2. **Manifest Validation:** 2 hooks (validating, validated)
+3. **Route Registration:** 2 hooks (before, after)
+4. **Dependency Management:** 2 hooks (checking, installed)
+5. **Configuration:** 2 hooks (loading, loaded)
+
+**Total:** 13 hooks operativos
+
+---
+
+**Documento creado:** 2026-02-16  
+**BlackCoffee:** v2.0.0  
+**Insitu Framework:** v1.2.1