blackcoffee2 2.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,435 @@
+# BlackCoffee App Server - Arquitectura v2.0.0
+
+## 📁 Estructura de Directorios
+
+```
+blackcoffee/
+├── server.js                    # Entry point del servidor
+├── bin/
+│   ├── adminclient              # Cliente administrativo TCP (existente)
+│   └── blackcoffee              # CLI de administración (nuevo)
+│
+├── core/                        # Núcleo del App Server
+│   ├── appLoader.js             # Carga y gestión de aplicaciones
+│   ├── appManager.js            # Manager de ciclo de vida (start/stop/restart)
+│   ├── configLoader.js          # Carga de configuración
+│   ├── manifestValidator.js     # Validación de manifests
+│   └── routeRegistrar.js        # Registro de rutas con prefijos
+│
+├── includes/                    # Utilidades y hooks
+│   ├── sessions.js              # Session manager (opcional)
+│   ├── routeLoader.js           # Cargador de rutas (existente)
+│   ├── adminExtension.js        # Consola administrativa (existente)
+│   ├── 404-hooks.js             # Manejo de errores 404 (existente)
+│   └── appHooks.js              # Hooks específicos para apps (nuevo)
+│
+├── apps/                        # Aplicaciones desplegadas
+│   └── {app-name}/
+│       └── {version}/
+│           ├── package.json     # Manifest + dependencias
+│           ├── app.js           # Entry point opcional (inicialización)
+│           ├── routes/          # Rutas en JSON
+│           │   └── static.json
+│           ├── controllers/     # Controladores de la app
+│           ├── models/          # Modelos de la app
+│           ├── views/           # Vistas de la app
+│           ├── public/          # Archivos estáticos de la app
+│           │   ├── assets/
+│           │   └── index.html
+│           └── node_modules/    # Dependencias específicas (opcional)
+│
+├── config/                      # Configuración del servidor
+│   ├── server.json              # Configuración principal
+│   ├── applications.json        # Estado de aplicaciones desplegadas
+│   └── security.json            # Configuración de seguridad
+│
+├── public/                      # Archivos estáticos globales
+│   ├── index.html               # Landing page del servidor
+│   └── assets/
+│
+├── routes/                      # Rutas globales (core)
+│   └── static.json
+│
+├── programatically/             # Rutas programáticas del núcleo
+│   ├── initFlow.js              # Inicialización de componentes
+│   └── PRoutes.js               # Rutas del núcleo (vacío por defecto)
+│
+├── docs/                        # Documentación
+│   ├── APP_HOOKS_REQUIREMENTS.md
+│   ├── ARCHITECTURE.md
+│   └── CLI_COMMANDS.md
+│
+├── deployeds/                   # DEPRECATED - Migrar a apps/
+│
+├── certs/                       # Certificados SSL
+├── issues/                      # Reporte de bugs
+├── package.json
+├── README.md
+└── CHANGELOG.md
+```
+
+---
+
+## 📦 Manifest de Aplicación (package.json)
+
+```json
+{
+  "name": "mi-app",
+  "version": "1.0.0",
+  "description": "Descripción de mi aplicación",
+  "author": "Tu Nombre <tu@email.com>",
+  "license": "MIT",
+  
+  "blackcoffee": {
+    "displayName": "Mi Aplicación",
+    "description": "Descripción larga para la UI Web",
+    "entryPoint": "routes/static.json",
+    "autoStart": true,
+    "minBlackCoffeeVersion": "2.0.0",
+    "routePrefix": null,
+    "category": "web",
+    "tags": ["ejemplo", "demo"],
+    "icon": "/public/icon.png"
+  },
+  
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "axios": "^1.4.0"
+  },
+  
+  "scripts": {
+    "start": "node app.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}
+```
+
+### Campos del Manifest
+
+| Campo | Requerido | Tipo | Descripción |
+|-------|-----------|------|-------------|
+| `name` | ✅ | string | Nombre único de la aplicación |
+| `version` | ✅ | string | Versión (semver) |
+| `blackcoffee.displayName` | ✅ | string | Nombre para mostrar en UI |
+| `blackcoffee.entryPoint` | ✅ | string | Ruta al archivo de rutas principal |
+| `blackcoffee.autoStart` | ⚠️ | boolean | Iniciar automáticamente al deploy |
+| `blackcoffee.minBlackCoffeeVersion` | ⚠️ | string | Versión mínima requerida |
+| `blackcoffee.routePrefix` | ⚠️ | string\|null | Prefijo custom (null = auto) |
+| `dependencies` | ⚠️ | object | Dependencias de npm |
+| `scripts` | ⚠️ | object | Scripts custom (start, test, etc.) |
+
+---
+
+## 🎯 Flujo de Deploy
+
+```
+1. blackcoffee deploy ./mi-app-1.0.0.tar.gz
+   ↓
+2. Extraer a apps/mi-app/1.0.0/
+   ↓
+3. Validar package.json (manifestValidator.js)
+   ↓
+4. hooks.doAction('app_deploying', manifest, tempPath)
+   ↓
+5. hooks.applyFilters('app_manifest_validating', ...)
+   ↓
+6. Instalar dependencias (npm install en apps/mi-app/1.0.0/)
+   ↓
+7. hooks.doAction('app_dependencies_installed', ...)
+   ↓
+8. Cargar routes desde entryPoint
+   ↓
+9. Para cada ruta:
+   hooks.applyFilters('before_app_routes_register', routeConfig, appName, version)
+   server.addRoute(modifiedRoute)
+   ↓
+10. hooks.doAction('after_app_routes_register', routes, appName, version)
+    ↓
+11. hooks.doAction('app_deployed', manifest, tempPath, deployedPath)
+    ↓
+12. Si autoStart=true: appManager.start(appName, version)
+    ↓
+13. Actualizar config/applications.json
+    ↓
+14. ✅ Deploy completado
+```
+
+---
+
+## 🔧 Hooks Nuevos Requeridos (Insitu Framework)
+
+### Application Lifecycle Hooks
+
+| Hook | Tipo | Parámetros | Descripción |
+|------|------|------------|-------------|
+| `app_deploying` | Action | `(manifest, tempPath)` | Antes de desplegar |
+| `app_deployed` | Action | `(manifest, tempPath, deployedPath)` | Después de desplegar |
+| `app_undeploying` | Action | `(appName, version)` | Antes de remover |
+| `app_undeployed` | Action | `(appName, version, removedPath)` | Después de remover |
+| `app_starting` | Action | `(appName, version)` | Antes de iniciar |
+| `app_started` | Action | `(appName, version)` | Después de iniciar |
+| `app_stopping` | Action | `(appName, version)` | Antes de detener |
+| `app_stopped` | Action | `(appName, version)` | Después de detener |
+| `app_restarting` | Action | `(appName, version)` | Antes de reiniciar |
+| `app_restarted` | Action | `(appName, version)` | Después de reiniciar |
+
+### Route Registration Hooks
+
+| Hook | Tipo | Parámetros | Descripción |
+|------|------|------------|-------------|
+| `before_app_routes_register` | Filter | `(routeConfig, appName, version)` | Antes de registrar ruta |
+| `after_app_routes_register` | Action | `(routes, appName, version)` | Después de registrar rutas |
+
+### Manifest Validation Hooks
+
+| Hook | Tipo | Parámetros | Descripción |
+|------|------|------------|-------------|
+| `app_manifest_validating` | Filter | `(isValid, manifest, errors)` | Durante validación |
+| `app_manifest_validated` | Action | `(manifest, isValid, errors)` | Después de validar |
+
+### Dependency Management Hooks
+
+| Hook | Tipo | Parámetros | Descripción |
+|------|------|------------|-------------|
+| `app_dependencies_checking` | Action | `(dependencies, appName, version)` | Antes de instalar deps |
+| `app_dependencies_installed` | Action | `(appName, version, success)` | Después de instalar deps |
+
+### Configuration Hooks
+
+| Hook | Tipo | Parámetros | Descripción |
+|------|------|------------|-------------|
+| `app_config_loading` | Filter | `(config, appName, version)` | Antes de cargar config |
+| `app_config_loaded` | Action | `(config, appName, version)` | Después de cargar config |
+
+---
+
+## 📊 Modificaciones a Insitu Framework
+
+### Archivo: `lib/core/hooks-handlers/server-start-hooks-handler.js`
+
+**Agregar:** Documentación de hooks de aplicación (solo documentación)
+
+### Archivo: `lib/admin/modules/QueueManagementModule.js`
+
+**Agregar:** Módulo `AppManagementModule` para administrar apps desde consola TCP
+
+### Nuevo Archivo: `lib/admin/modules/AppManagementModule.js`
+
+```javascript
+/**
+ * Módulo de Administración de Aplicaciones para BlackCoffee
+ * Permite gestionar aplicaciones desplegadas desde la consola TCP
+ */
+
+class AppManagementModule {
+  constructor(adminExtension) {
+    this.adminExtension = adminExtension;
+    this.name = 'App Management Module';
+    this.description = 'Gestión de aplicaciones desplegadas';
+    this.commands = [
+      'apps-list',
+      'apps-deploy',
+      'apps-undeploy',
+      'apps-start',
+      'apps-stop',
+      'apps-restart',
+      'apps-status',
+      'apps-info'
+    ];
+  }
+
+  handleCommand(command, socket) {
+    const parts = command.split(' ');
+    const subCommand = parts[0];
+    
+    switch (subCommand) {
+      case 'apps-list':
+        this.listApps(socket);
+        break;
+      case 'apps-deploy':
+        this.deployApp(socket, parts.slice(1).join(' '));
+        break;
+      // ... más comandos
+      default:
+        socket.write(`Comando desconocido: ${subCommand}\n`);
+    }
+  }
+
+  listApps(socket) {
+    const apps = this.adminExtension.frameworkInstance.appManager?.getApps() || [];
+    socket.write(`\nAplicaciones desplegadas: ${apps.length}\n\n`);
+    
+    apps.forEach(app => {
+      const status = app.running ? '▶️' : '⏹️';
+      socket.write(`  ${status} ${app.name} v${app.version}\n`);
+    });
+    
+    socket.write(`\n> `);
+  }
+}
+
+module.exports = AppManagementModule;
+```
+
+---
+
+## 🖥️ CLI Commands (Roadmap)
+
+### Comandos Básicos
+
+```bash
+# Deploy de aplicación
+blackcoffee app:deploy ./mi-app-1.0.0.tar.gz
+
+# Listar aplicaciones
+blackcoffee app:list
+
+# Ver estado de una app
+blackcoffee app:status mi-app
+
+# Iniciar aplicación
+blackcoffee app:start mi-app 1.0.0
+
+# Detener aplicación
+blackcoffee app:stop mi-app 1.0.0
+
+# Reiniciar aplicación
+blackcoffee app:restart mi-app 1.0.0
+
+# Undeploy
+blackcoffee app:undeploy mi-app 1.0.0
+
+# Ver logs
+blackcoffee app:logs mi-app --tail=100
+
+# Ver información detallada
+blackcoffee app:info mi-app 1.0.0
+```
+
+### Comandos de Configuración
+
+```bash
+# Listar configuraciones
+blackcoffee config:list
+
+# Obtener configuración
+blackcoffee config:get server.port
+
+# Establecer configuración
+blackcoffee config:set server.port 9791
+
+# Reiniciar servidor
+blackcoffee server:restart
+```
+
+---
+
+## 🌐 UI Web - Consideraciones Futuras
+
+### API Endpoints para UI
+
+```javascript
+// GET /api/admin/apps
+// Lista todas las aplicaciones desplegadas
+
+// GET /api/admin/apps/:name/:version
+// Información detallada de una app
+
+// POST /api/admin/apps/deploy
+// Deploy de nueva aplicación (multipart/form-data)
+
+// POST /api/admin/apps/:name/:version/start
+// Iniciar aplicación
+
+// POST /api/admin/apps/:name/:version/stop
+// Detener aplicación
+
+// DELETE /api/admin/apps/:name/:version
+// Undeploy de aplicación
+
+// GET /api/admin/apps/:name/:version/logs
+// Logs de la aplicación
+
+// GET /api/admin/stats
+// Estadísticas del servidor
+```
+
+### Estructura de Respuesta API
+
+```json
+{
+  "success": true,
+  "data": {
+    "apps": [
+      {
+        "name": "mi-app",
+        "version": "1.0.0",
+        "displayName": "Mi Aplicación",
+        "status": "running",
+        "deployedAt": "2026-02-16T12:00:00.000Z",
+        "startedAt": "2026-02-16T12:01:00.000Z",
+        "routes": 5,
+        "dependencies": {
+          "lodash": "^4.17.21"
+        },
+        "metrics": {
+          "requests": 1234,
+          "errors": 5,
+          "avgResponseTime": 45
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 📝 Archivos a Crear
+
+### Fase 1: Núcleo
+
+- [ ] `core/appLoader.js` - Carga de aplicaciones
+- [ ] `core/appManager.js` - Manager de ciclo de vida
+- [ ] `core/configLoader.js` - Carga de configuración
+- [ ] `core/manifestValidator.js` - Validación de manifests
+- [ ] `core/routeRegistrar.js` - Registro de rutas
+- [ ] `includes/appHooks.js` - Hooks específicos para apps
+- [ ] `config/server.json` - Configuración principal
+- [ ] `config/applications.json` - Estado de apps
+
+### Fase 2: CLI
+
+- [ ] `bin/blackcoffee` - CLI ejecutable
+- [ ] `cli/commands/app.js` - Comandos de aplicaciones
+- [ ] `cli/commands/config.js` - Comandos de configuración
+- [ ] `cli/commands/server.js` - Comandos de servidor
+- [ ] `cli/utils/deployer.js` - Utilidades de deploy
+- [ ] `cli/utils/validator.js` - Validaciones
+
+### Fase 3: Insitu Modifications
+
+- [ ] `lib/admin/modules/AppManagementModule.js` - Módulo admin TCP
+- [ ] `lib/core/hooks-handlers/app-hooks-handler.js` - Handlers oficiales
+- [ ] Documentación en `hooks_filters_documentation.md`
+
+### Fase 4: UI Web (Futuro)
+
+- [ ] `routes/admin.json` - Rutas de administración
+- [ ] `controllers/AdminController.js` - Controlador admin
+- [ ] `public/admin/` - UI Web estática
+
+---
+
+## ✅ Próximo Paso
+
+Implementar **Fase 1: Núcleo** comenzando por:
+1. `includes/appHooks.js` - Todos los hooks
+2. `core/appLoader.js` - Carga de aplicaciones
+3. `core/manifestValidator.js` - Validación
+
+---
+
+**Documento creado:** 2026-02-16  
+**Versión:** 1.0  
+**BlackCoffee:** v2.0.0-app-server