blackcoffee2 2.1.0

package/issues/001-duplicate-module-loading.md

@@ -0,0 +1,92 @@
+# Issue: Duplicate Module Loading in AdminExtension
+
+## Report Date
+2026-02-16
+
+## Affected Component
+**File:** `lib/admin/AdminExtension.js`  
+**Framework:** Insitu Framework v1.2.0
+
+## Problem Description
+
+Modules are being loaded **twice** during the initialization of the AdminExtension, causing duplicate log messages and potential performance issues.
+
+## Root Cause
+
+In the `initialize()` method, both `registerModules()` and `loadCustomModules()` are called separately:
+
+```javascript
+// Line 63-68 in AdminExtension.js
+this.registerModules();
+this.loadCustomModules();  // ← First call
+```
+
+However, `registerModules()` **also** calls `loadCustomModules()` internally:
+
+```javascript
+// Line 173 in AdminExtension.js
+registerModules() {
+  // ... register default modules ...
+  
+  this.loadCustomModules();  // ← Second call (duplicate)
+}
+```
+
+## Evidence
+
+When starting the BlackCoffee server, the log shows duplicate messages:
+
+```
+Módulo 'WAFModule' cargado exitosamente.
+Módulo 'WAFModule' cargado exitosamente.  ← Duplicate
+
+Módulo 'CacheModule' cargado exitosamente.
+Módulo 'CacheModule' cargado exitosamente.  ← Duplicate
+
+// ... all modules show the same pattern
+```
+
+## Impact
+
+1. **Duplicate log messages** - Confusing for developers
+2. **Potential memory leaks** - Modules might be registered twice in the modules Map
+3. **Performance overhead** - Unnecessary file system operations
+4. **Event handler duplication** - Hooks might be registered multiple times
+
+## Suggested Fix
+
+Remove the redundant `loadCustomModules()` call from the `initialize()` method:
+
+```javascript
+// CURRENT CODE (lines 63-68):
+this.registerModules();
+this.loadCustomModules();  // ← REMOVE THIS LINE
+
+// FIXED CODE:
+this.registerModules();  // This already calls loadCustomModules() internally
+```
+
+## Files to Modify
+
+- `lib/admin/AdminExtension.js` - Line 68 (remove the call to `loadCustomModules()`)
+
+## Testing
+
+After applying the fix, verify that:
+1. Each module loads only once (check logs)
+2. All admin commands still work correctly
+3. Custom modules from `./modules` directory still load properly
+4. No functionality is broken
+
+## Workaround (for BlackCoffee)
+
+Until this is fixed in the framework, BlackCoffee can patch the file locally or tolerate the duplicate loading (it doesn't break functionality, just creates noise in logs).
+
+## Priority
+
+**Medium** - Doesn't break functionality but causes confusion and potential issues.
+
+## Reported By
+
+BlackCoffee Team  
+Repository: https://gitlab.com/bytedogssyndicate1/bc2

package/manuales/ADMIN_EXTENSION_COMMANDS_MANUAL.md

@@ -0,0 +1,261 @@
+# Manual de Extensión de Comandos para la Extensión de Administración de Insitu
+
+## Introducción
+
+Este manual explica cómo crear nuevos comandos para la extensión de administración de Insitu Framework. La extensión está diseñada con una arquitectura modular que permite añadir fácilmente nuevas funcionalidades.
+
+## Arquitectura de la Extensión
+
+La extensión de administración está construida con un sistema de módulos donde cada módulo puede definir comandos y un handler para procesarlos.
+
+### Estructura de un Módulo
+
+```javascript
+{
+  name: 'Nombre del Módulo',
+  description: 'Descripción del módulo',
+  commands: ['comando1', 'comando2'],  // Lista de comandos que maneja
+  handler: function(command, socket) {  // Función que maneja los comandos
+    // Lógica para manejar los comandos
+  }
+}
+```
+
+## Cómo Crear un Nuevo Módulo con Comandos
+
+### Paso 1: Localizar el Archivo de la Extensión
+
+El archivo principal de la extensión se encuentra en:
+`/lib/admin/AdminExtension.js`
+
+### Paso 2: Registrar un Nuevo Módulo
+
+En el método `registerModules()`, añade tu nuevo módulo:
+
+```javascript
+/**
+ * Registra los módulos de administración
+ */
+registerModules() {
+  // Módulo de rutas - el primer módulo
+  this.modules.set('routes', {
+    name: 'Routes Module',
+    description: 'Módulo para ver rutas registradas y activas',
+    commands: ['routes', 'active'],
+    handler: this.handleRoutesCommand.bind(this)
+  });
+  
+  // Módulo de sistema - para comandos generales
+  this.modules.set('system', {
+    name: 'System Module',
+    description: 'Módulo para información del sistema',
+    commands: ['version', 'status', 'help'],
+    handler: this.handleSystemCommand.bind(this)
+  });
+  
+  // TU NUEVO MÓDULO AQUÍ
+  this.modules.set('mymodule', {
+    name: 'My Custom Module',
+    description: 'Módulo para funcionalidades personalizadas',
+    commands: ['mycommand', 'anothercommand'],
+    handler: this.handleMyModuleCommand.bind(this)
+  });
+}
+```
+
+### Paso 3: Crear el Handler del Módulo
+
+Después de registrar el módulo, debes crear la función handler que procesará los comandos:
+
+```javascript
+/**
+ * Manejador para el módulo personalizado
+ */
+handleMyModuleCommand(command, socket) {
+  switch (command) {
+    case 'mycommand':
+      this.handleMyCommand(socket);
+      break;
+    case 'anothercommand':
+      this.handleAnotherCommand(socket);
+      break;
+    default:
+      socket.write(`Comando desconocido para el módulo: ${command}\n`);
+      socket.write(`Comandos disponibles: mycommand, anothercommand\n\n`);
+      socket.write(`> `);
+  }
+}
+
+/**
+ * Maneja el comando 'mycommand'
+ */
+handleMyCommand(socket) {
+  socket.write('\n=== Mi Comando Personalizado ===\n');
+  socket.write('Este es un ejemplo de comando personalizado.\n');
+  socket.write('Puedes añadir cualquier lógica aquí.\n\n');
+  socket.write('> ');
+}
+
+/**
+ * Maneja el comando 'anothercommand'
+ */
+handleAnotherCommand(socket) {
+  socket.write('\n=== Otro Comando ===\n');
+  socket.write('Este es otro ejemplo de comando.\n\n');
+  socket.write('> ');
+}
+```
+
+## Ejemplo Completo: Módulo de Estadísticas
+
+Aquí tienes un ejemplo completo de cómo crear un módulo de estadísticas:
+
+```javascript
+/**
+ * Registra los módulos de administración
+ */
+registerModules() {
+  // ... otros módulos ...
+
+  // Módulo de estadísticas
+  this.modules.set('stats', {
+    name: 'Statistics Module',
+    description: 'Módulo para ver estadísticas del servidor',
+    commands: ['stats', 'memory', 'requests'],
+    handler: this.handleStatsCommand.bind(this)
+  });
+}
+
+/**
+ * Manejador para el módulo de estadísticas
+ */
+handleStatsCommand(command, socket) {
+  switch (command) {
+    case 'stats':
+      this.showGeneralStats(socket);
+      break;
+    case 'memory':
+      this.showMemoryStats(socket);
+      break;
+    case 'requests':
+      this.showRequestStats(socket);
+      break;
+    default:
+      socket.write(`Comando desconocido para el módulo de estadísticas: ${command}\n`);
+      socket.write(`Comandos disponibles: stats, memory, requests\n\n`);
+      socket.write(`> `);
+  }
+}
+
+/**
+ * Muestra estadísticas generales
+ */
+showGeneralStats(socket) {
+  const uptime = process.uptime();
+  const totalRequests = this.activeRoutes.size;
+  
+  socket.write('\n=== Estadísticas Generales ===\n');
+  socket.write(`Tiempo de actividad: ${Math.floor(uptime)} segundos\n`);
+  socket.write(`Solicitudes procesadas: ${totalRequests}\n`);
+  socket.write(`Clientes conectados: ${this.clients.size}\n\n`);
+  socket.write(`> `);
+}
+
+/**
+ * Muestra estadísticas de memoria
+ */
+showMemoryStats(socket) {
+  const memUsage = process.memoryUsage();
+  
+  socket.write('\n=== Uso de Memoria ===\n');
+  socket.write(`RSS: ${(memUsage.rss / 1024 / 1024).toFixed(2)} MB\n`);
+  socket.write(`Heap Total: ${(memUsage.heapTotal / 1024 / 1024).toFixed(2)} MB\n`);
+  socket.write(`Heap Used: ${(memUsage.heapUsed / 1024 / 1024).toFixed(2)} MB\n`);
+  socket.write(`External: ${(memUsage.external / 1024 / 1024).toFixed(2)} MB\n\n`);
+  socket.write(`> `);
+}
+
+/**
+ * Muestra estadísticas de solicitudes
+ */
+showRequestStats(socket) {
+  socket.write('\n=== Estadísticas de Solicitudes ===\n');
+  socket.write(`Solicitudes activas registradas: ${this.activeRoutes.size}\n`);
+  
+  if (this.activeRoutes.size > 0) {
+    socket.write('Métodos HTTP utilizados:\n');
+    const methods = {};
+    for (const [url, info] of this.activeRoutes) {
+      methods[info.method] = (methods[info.method] || 0) + 1;
+    }
+    
+    for (const [method, count] of Object.entries(methods)) {
+      socket.write(`  ${method}: ${count} solicitudes\n`);
+    }
+  }
+  
+  socket.write('\n> ');
+}
+```
+
+## Buenas Prácticas
+
+1. **Nombres de comandos claros**: Usa nombres descriptivos y cortos para los comandos.
+
+2. **Manejo de errores**: Siempre incluye un caso `default` en los switches para manejar comandos desconocidos.
+
+3. **Formato consistente**: Mantén un formato consistente en las respuestas para mejorar la experiencia del usuario.
+
+4. **Prompts finales**: Asegúrate de escribir `> ` al final de cada comando para mostrar el prompt.
+
+5. **Documentación**: Documenta cada nuevo comando y su funcionalidad.
+
+## Integración con Hooks del Framework
+
+Puedes integrar tu módulo con los hooks del framework para capturar eventos en tiempo real:
+
+```javascript
+/**
+ * Registra los hooks necesarios para rastrear rutas
+ */
+registerHooks() {
+  if (this.hooks) {
+    // Hook para rastrear rutas registradas
+    this.hooks.addAction('route_registered', (route) => {
+      this.registeredRoutes.push(route);
+    });
+
+    // Hook para rastrear rutas activas
+    this.hooks.addAction('request_received', (req, res) => {
+      const routeInfo = {
+        method: req.method,
+        url: req.url,
+        timestamp: new Date().toISOString(),
+        remoteAddress: req.connection.remoteAddress
+      };
+
+      // Usar la URL como clave y almacenar la última solicitud
+      this.activeRoutes.set(req.url, routeInfo);
+
+      // Disparar hook específico para módulos de administración
+      this.hooks.doAction('admin_route_active', routeInfo);
+    });
+
+    // Hook para cuando se cierra el servidor
+    this.hooks.addAction('server_stopped', () => {
+      this.close();
+    });
+    
+    // Añade aquí tus propios hooks personalizados
+    this.hooks.addAction('my_custom_event', (data) => {
+      // Procesa el evento personalizado
+    });
+  }
+}
+```
+
+## Conclusión
+
+Crear nuevos comandos para la extensión de administración es sencillo gracias a su arquitectura modular. Simplemente registra un nuevo módulo con sus comandos y handler, y la extensión se encargará del resto.
+
+La extensión está diseñada para ser fácilmente extensible, permitiendo añadir nuevas funcionalidades de administración según las necesidades del proyecto.

package/manuales/ADMIN_EXTENSION_HOOK_EXAMPLE.md

@@ -0,0 +1,28 @@
+/**
+ * Ejemplo de uso del hook para inicializar la extensión de administración
+ * 
+ * Este archivo demuestra cómo usar el hook 'admin_extensions_initialize'
+ * para inicializar la extensión de administración después de que el servidor
+ * esté completamente iniciado y todas las rutas hayan sido cargadas.
+ */
+
+// Suponiendo que tienes acceso al sistema de hooks
+const { hooks } = require('insitu');
+
+// Registrar un listener para el hook de inicialización de extensiones
+hooks.addAction('admin_extensions_initialize', (server) => {
+  console.log('Inicializando extensión de administración...');
+  
+  // Inicializar la extensión de administración
+  server.initializeAdminExtension({
+    port: 9999,
+    host: '127.0.0.1'
+  });
+  
+  console.log('Extensión de administración inicializada.');
+});
+
+/**
+ * Alternativamente, puedes usar un archivo de configuración de hooks
+ * como el que se usa en test-app/hooks-config.js
+ */

package/manuales/ADMIN_EXTENSION_INTEGRATION_MANUAL.md

@@ -0,0 +1,232 @@
+# Manual de Integración de la Extensión de Administración
+
+## Introducción
+
+Este manual explica cómo integrar la extensión de administración de Insitu Framework en tus proyectos. La extensión proporciona un servidor TCP de administración que permite monitorear y gestionar tu aplicación en tiempo real.
+
+## Características
+
+- **Servidor TCP de administración**: Accesible solo desde localhost por seguridad
+- **Monitoreo en tiempo real**: Visualización de rutas registradas y activas
+- **Sistema de módulos extensible**: Arquitectura para añadir nuevas funcionalidades
+- **Integración con hooks**: Sistema de extensibilidad basado en el sistema de hooks del framework
+- **Puerto configurable**: Por defecto en el puerto 9999
+
+## Requisitos Previos
+
+- Insitu Framework v1.0.0 o superior
+- Node.js 14.0.0 o superior
+- Acceso a la instancia del servidor APIServer
+
+## Instalación
+
+La extensión de administración ya viene incluida en Insitu Framework v1.0.0+, por lo que no requiere instalación adicional.
+
+## Integración Básica
+
+### Método 1: Inicialización Directa
+
+```javascript
+const { APIServer } = require('insitu');
+
+const server = new APIServer({ port: 3000 });
+
+// Inicializar la extensión de administración
+server.initializeAdminExtension({
+  port: 9999,
+  host: '127.0.0.1'  // Solo localhost (recomendado)
+});
+
+server.start();
+```
+
+### Método 2: Con Opciones Personalizadas
+
+```javascript
+const { APIServer } = require('insitu');
+
+const server = new APIServer({ 
+  port: 3000,
+  host: 'localhost'
+});
+
+// Inicializar con opciones personalizadas
+server.initializeAdminExtension({
+  port: 9999,           // Puerto personalizado (por defecto: 9999)
+  host: '127.0.0.1'    // Host personalizado (por defecto: '127.0.0.1')
+});
+
+server.start();
+```
+
+## Integración con Carga de Rutas
+
+### Recomendado: Después de Cargar Rutas
+
+Para asegurar que la extensión capture todas las rutas registradas, es recomendable inicializarla después de cargar las rutas:
+
+```javascript
+const { 
+  APIServer, 
+  RouteDirectoryLoader,
+  ViewEngine,
+  ModelManager 
+} = require('insitu');
+
+const server = new APIServer({ port: 3000 });
+
+// Configurar otros componentes
+const viewEngine = new ViewEngine({ viewsDir: './views' });
+const modelManager = new ModelManager();
+server.viewEngine = viewEngine;
+server.modelManager = modelManager;
+
+// Cargar rutas desde directorio
+const routeDirectoryLoader = new RouteDirectoryLoader();
+routeDirectoryLoader.loadRoutesFromDirectory(server, './routes')
+    .then(routes => {
+        console.log(`${routes.length} rutas cargadas exitosamente`);
+
+        // Inicializar la extensión de administración DESPUÉS de cargar rutas
+        server.initializeAdminExtension({
+          port: 9999,
+          host: '127.0.0.1'
+        });
+
+        // Iniciar el servidor
+        server.start();
+    })
+    .catch(error => {
+        console.error('Error cargando rutas:', error.message);
+    });
+```
+
+## Integración en Diferentes Puntos del Ciclo de Vida
+
+### Durante la Configuración del Servidor
+
+```javascript
+const { APIServer, SessionManager } = require('insitu');
+
+const server = new APIServer({ port: 3000 });
+
+// Configurar sesión
+const sessionManager = new SessionManager();
+server.use(sessionManager.middleware());
+
+// Inicializar extensión de administración en cualquier punto
+server.initializeAdminExtension({
+  port: 9999,
+  host: '127.0.0.1'
+});
+
+server.start();
+```
+
+### Usando el Hook de Inicialización de Extensiones (Recomendado)
+
+Para garantizar que la extensión se inicialice después de que todas las rutas hayan sido completamente cargadas y el servidor esté operativo, puedes usar el hook `admin_extensions_initialize`:
+
+```javascript
+const { hooks } = require('insitu');
+
+// Registrar un listener para el hook de inicialización de extensiones
+hooks.addAction('admin_extensions_initialize', (server) => {
+  // Inicializar la extensión de administración después de que el servidor esté completamente iniciado
+  server.initializeAdminExtension({
+    port: 9999,
+    host: '127.0.0.1'
+  });
+});
+```
+
+Este enfoque garantiza que la extensión de administración se inicialice en el momento óptimo del ciclo de vida del servidor, después de que todas las rutas hayan sido cargadas y el servidor esté completamente operativo.
+
+### En Middleware o Controladores
+
+La extensión se puede inicializar en cualquier momento, incluso en middleware o controladores, aunque no es recomendable:
+
+```javascript
+// En un archivo de middleware
+function initializeAdminIfNotExists(req, res, next) {
+  if (!req.server.adminExtension) {
+    req.server.initializeAdminExtension({
+      port: 9999,
+      host: '127.0.0.1'
+    });
+  }
+  next();
+}
+```
+
+## Comandos Disponibles
+
+Una vez iniciada la extensión, puedes conectarte usando telnet o nc:
+
+```bash
+telnet localhost 9999
+# o
+nc localhost 9999
+```
+
+### Comandos del Módulo de Rutas:
+- `routes` - Muestra las rutas registradas
+- `active` - Muestra las rutas activas (solicitudes recientes)
+
+### Comandos del Módulo de Sistema:
+- `version` - Muestra la versión del framework
+- `status` - Muestra el estado del servidor
+- `help` - Muestra la ayuda
+
+### Comandos Generales:
+- `help` - Muestra la ayuda general
+- `quit` - Cierra la conexión
+
+## Seguridad
+
+- El servidor de administración solo escucha en localhost (127.0.0.1) por defecto
+- No es accesible desde fuera de la máquina local
+- Se recomienda mantener el puerto 9999 (o el puerto elegido) detrás del firewall
+- No enviar información sensible a través de la conexión de administración
+
+## Configuración Avanzada
+
+### Puerto Personalizado
+
+```javascript
+server.initializeAdminExtension({
+  port: 8888,  // Puerto personalizado
+  host: '127.0.0.1'
+});
+```
+
+### Múltiples Instancias (No Recomendado)
+
+Aunque técnicamente posible, no se recomienda inicializar múltiples extensiones de administración en el mismo servidor.
+
+## Troubleshooting
+
+### El comando `routes` no muestra rutas
+- Asegúrate de que la extensión se inicialice después de cargar las rutas
+- Verifica que las rutas se hayan registrado correctamente
+
+### No puedo conectarme al puerto
+- Verifica que el puerto esté disponible
+- Asegúrate de que el firewall no esté bloqueando la conexión
+- Confirma que la extensión se haya inicializado correctamente
+
+### Comandos no reconocidos
+- Asegúrate de estar usando la versión correcta de Insitu Framework
+- Verifica que la extensión se haya inicializado correctamente
+
+## Buenas Prácticas
+
+1. **Inicializar después de cargar rutas**: Para capturar todas las rutas registradas
+2. **Usar localhost**: Siempre usar 127.0.0.1 como host para seguridad
+3. **Puerto dedicado**: Usar un puerto diferente al del servidor web principal
+4. **Entornos de desarrollo**: Adecuado para entornos de desarrollo y pruebas
+5. **No en producción**: No se recomienda usar en entornos de producción sin medidas de seguridad adicionales
+
+## Conclusión
+
+La extensión de administración se integra de forma transparente en Insitu Framework y proporciona herramientas poderosas para monitorear y gestionar tu aplicación. La integración es simple y flexible, permitiendo inicializarla en cualquier punto del ciclo de vida del servidor.