@arela/uploader 1.0.24 → 1.1.0

package/docs/PLAN_WATCH_FEATURE.md

@@ -0,0 +1,417 @@
+# Plan de Implementación: Feature de Observación de Directorios (Watch)
+
+## 📋 Resumen Ejecutivo
+
+Implementar una funcionalidad de **observación de directorios (Watch Mode)** que permita monitorear uno o varios directorios en tiempo real y ejecutar automáticamente la subida de archivos nuevos o cambios en la estructura de carpetas.
+
+---
+
+## 🎯 Objetivos
+
+1. Monitorear uno o múltiples directorios especificados
+2. Detectar cambios: archivos nuevos, modificados o eliminados
+3. Ejecutar automáticamente el pipeline de upload al detectar cambios
+4. Permitir diferentes estrategias de subida (archivo individual, estructura completa, etc.)
+5. Mantener logging detallado de eventos de watch
+6. Proporcionar opciones de configuración flexible
+
+---
+
+## 📐 Arquitectura Propuesta
+
+### 1. **WatchService** (Nuevo Servicio Principal)
+**Ubicación**: `src/services/WatchService.js`
+
+```
+WatchService
+├── Configuración de directorios a observar
+├── Inicialización de watchers
+├── Manejo de eventos (add, change, unlink)
+├── Debouncing de eventos
+├── Gestión de estado
+└── Integración con UploadCommand
+```
+
+**Responsabilidades**:
+- Usar librería `chokidar` para observar cambios del filesystem
+- Configurar watchers para múltiples directorios
+- Implementar debouncing para evitar múltiples triggers rápidos
+- Ejecutar callbacks de upload cuando se detecten cambios
+- Mantener estadísticas de cambios detectados
+
+### 2. **WatchCommand** (Nuevo Comando CLI)
+**Ubicación**: `src/commands/WatchCommand.js`
+
+```
+WatchCommand
+├── Parsear opciones CLI
+├── Inicializar WatchService
+├── Manejar señales (SIGINT, SIGTERM)
+├── Mostrar estado en tiempo real
+└── Manejo de errores
+```
+
+**Responsabilidades**:
+- Ejecutar el servicio de watch
+- Mantener proceso activo
+- Manejo graceful shutdown
+- Mostrar feedback visual al usuario
+
+### 3. **Opciones de Configuración**
+
+#### En `config.js`:
+```javascript
+watch: {
+  enabled: boolean,
+  directories: string[], // Directorios a observar
+  usePolling: boolean, // Usar polling en lugar de eventos nativos
+  interval: number, // Intervalo de polling en ms
+  awaitWriteFinish: {
+    stabilityThreshold: number, // Esperar ms antes de trigger
+    pollInterval: number
+  },
+  debounceMs: number, // Debouncing de eventos
+  ignorePatterns: string[], // Patrones a ignorar (node_modules, .git, etc)
+  autoUploadOnChange: boolean, // Subir automáticamente
+  uploadStrategy: 'individual' | 'batch' | 'full-structure'
+}
+```
+
+#### En `.env`:
+```
+WATCH_ENABLED=true
+WATCH_DIRECTORIES=/path/to/dir1,/path/to/dir2
+WATCH_DEBOUNCE_MS=1000
+WATCH_AUTO_UPLOAD=true
+WATCH_STRATEGY=batch
+```
+
+---
+
+## 🏗️ Estructura de Archivos a Crear/Modificar
+
+### ✨ Nuevos Archivos
+
+```
+src/
+├── services/
+│   └── WatchService.js          # Servicio principal de watch
+├── commands/
+│   └── WatchCommand.js          # Comando CLI para watch
+└── utils/
+    └── WatchEventHandler.js     # Manejador de eventos de watch
+```
+
+### 📝 Archivos a Modificar
+
+```
+src/
+├── index.js                      # Agregar comando 'watch'
+├── config/config.js              # Agregar configuración de watch
+└── services/LoggingService.js    # Mejorar logging para eventos de watch
+```
+
+### 📦 Dependencias a Agregar
+
+```json
+{
+  "chokidar": "^3.6.0"  // Observador de filesystem multiplataforma
+}
+```
+
+---
+
+## 🔄 Flujo de Funcionamiento
+
+### 1. Inicio del Watch Mode
+```
+Usuario ejecuta: arela watch --directories /path/to/folder
+                   ↓
+    Validar configuración y directorios
+                   ↓
+    Inicializar WatchService
+                   ↓
+    Crear watchers para cada directorio
+                   ↓
+    Mostrar mensaje "Watching directories..."
+                   ↓
+    Mantener proceso activo (Ctrl+C para salir)
+```
+
+### 2. Detección de Cambios
+```
+Chokidar detecta cambio
+                   ↓
+    WatchEventHandler procesa evento
+                   ↓
+    Aplicar debouncing (esperar eventos adicionales)
+                   ↓
+    Determinar archivos afectados
+                   ↓
+    Ejecutar estrategia de upload:
+    - individual: subir solo el archivo nuevo/modificado
+    - batch: subir grupo de cambios recientes
+    - full-structure: subir estructura completa afectada
+                   ↓
+    Logging de resultado
+```
+
+### 3. Manejo de Errores
+```
+Error detectado durante watch
+                   ↓
+    Loguear error con contexto
+                   ↓
+    Continuar observando (no salir)
+                   ↓
+    Opcionalmente notificar usuario
+```
+
+---
+
+## 🛠️ Interfaces de Comando CLI
+
+### Comando Principal
+```bash
+# Watch modo básico (usa config)
+arela watch
+
+# Especificar directorios
+arela watch --directories ./uploads,./documents
+
+# Con opciones adicionales
+arela watch \
+  --directories ./uploads \
+  --strategy batch \
+  --debounce 2000 \
+  --batch-size 10 \
+  --auto-detect \
+  --verbose
+
+# Watch con configuración personalizada
+arela watch --config ./watch-config.json
+```
+
+### Opciones Disponibles
+```
+--directories <paths>        Directorios a observar (separados por coma)
+--strategy <strategy>        batch|individual|full-structure (default: batch)
+--debounce <ms>             Debounce en milisegundos (default: 1000)
+--batch-size <size>         Tamaño de batch para upload (default: 10)
+--poll <ms>                 Usar polling cada N ms
+--ignore <patterns>         Patrones a ignorar
+--auto-detect               Detección automática de documentos
+--auto-organize             Organización automática
+--verbose                   Modo verbose
+--dry-run                   Simular cambios sin subir
+--config <path>             Cargar configuración de archivo
+```
+
+---
+
+## 📊 Estados y Transiciones
+
+```
+┌─────────────────┐
+│   STOPPED       │
+└────────┬────────┘
+         │ arela watch
+         ↓
+┌─────────────────┐
+│   INITIALIZING  │◄───────────────────────┐
+└────────┬────────┘                        │
+         │                                  │
+         ↓ Watchers listos                  │
+┌─────────────────┐                        │
+│   WATCHING      │                        │
+│                 │                        │
+│ (detectando)    │                        │
+└────────┬────────┘                        │
+         │                                  │
+         ├─► Archivo nuevo/modificado      │
+         │        ↓                         │
+         │  ┌──────────────┐                │
+         │  │  PROCESSING  │                │
+         │  └──────┬───────┘                │
+         │         │ Upload completado     │
+         │         ↓                        │
+         │  ┌──────────────┐                │
+         │  │  UPLOADED    │────────────────┤
+         │  └──────────────┘                │
+         │                                  │
+         ├─► Ctrl+C                        │
+         ↓                                  │
+┌─────────────────┐                        │
+│   STOPPING      │────────────────────────┤
+└────────┬────────┘                        │
+         │ Cleanup completado              │
+         ↓                                  │
+┌─────────────────┐                        │
+│   STOPPED       │────────────────────────┘
+└─────────────────┘
+```
+
+---
+
+## 📋 Checkpoints de Implementación
+
+### **Fase 1: Fundaciones** ✅
+- [ ] Agregar dependencia `chokidar` a `package.json`
+- [ ] Crear `WatchService.js` con estructura básica
+- [ ] Implementar métodos de inicialización y limpieza
+- [ ] Crear `WatchCommand.js` básico
+- [ ] Agregar comando `watch` a `index.js`
+
+### **Fase 2: Funcionalidad Core** 🔧
+- [ ] Implementar manejo de eventos (add, change, unlink)
+- [ ] Agregar debouncing de eventos
+- [ ] Implementar detección de cambios
+- [ ] Crear `WatchEventHandler.js`
+- [ ] Integrar con `UploadCommand`
+
+### **Fase 3: Configuración** ⚙️
+- [ ] Agregar opciones de watch a `config.js`
+- [ ] Implementar parseo de variables de ambiente
+- [ ] Crear validador de configuración
+- [ ] Agregar opciones CLI al comando `watch`
+
+### **Fase 4: Estrategias de Upload** 🎯
+- [ ] Implementar estrategia `individual`
+- [ ] Implementar estrategia `batch`
+- [ ] Implementar estrategia `full-structure`
+- [ ] Sistema de selección de estrategia
+
+### **Fase 5: Logging y Monitoreo** 📊
+- [ ] Mejorar logging de eventos de watch
+- [ ] Agregar estadísticas en tiempo real
+- [ ] Mostrar progress bars para uploads
+- [ ] Sistema de notificaciones de error
+
+### **Fase 6: Manejo de Señales y Cleanup** 🛑
+- [ ] Implementar manejo de SIGINT/SIGTERM
+- [ ] Graceful shutdown de watchers
+- [ ] Finalización de uploads en progreso
+- [ ] Reporte final de sesión
+
+### **Fase 7: Testing y Documentación** 📚
+- [ ] Crear ejemplos de uso
+- [ ] Actualizar README.md
+- [ ] Documentar opciones CLI
+- [ ] Crear guía de troubleshooting
+
+---
+
+## 🔍 Consideraciones Técnicas
+
+### 1. **Rendimiento**
+- Usar debouncing para evitar múltiples triggers
+- Implementar `awaitWriteFinish` para esperar escritura completa
+- Considerar `usePolling` para sistemas de archivos remotos
+- Limitar batch size para evitar sobrecargar sistema
+
+### 2. **Compatibilidad Multiplataforma**
+- `chokidar` maneja diferencias entre Windows, macOS, Linux
+- Usar rutas con `/` (chokidar normaliza automáticamente)
+- Probar con UNC paths en Windows
+
+### 3. **Manejo de Errores**
+- No detener watch si falla un upload
+- Loguear errores para debugging
+- Reintentar según configuración
+
+### 4. **Seguridad**
+- Validar directorios especificados existen y son legibles
+- Respetar permisos del filesystem
+- No escalar privilegios automáticamente
+
+### 5. **Consumo de Recursos**
+- Limitar número de watchers simultáneos
+- Implementar cleanup apropiado de listeners
+- Monitorear memoria en watches de larga duración
+
+---
+
+## 📌 Variables de Ambiente Nuevas
+
+```bash
+# Habilitar/deshabilitar watch mode
+WATCH_ENABLED=true
+
+# Directorios a observar (separados por coma)
+WATCH_DIRECTORIES=/ruta/a/carpeta1,/ruta/a/carpeta2
+
+# Estrategia de upload
+WATCH_STRATEGY=batch  # Options: individual|batch|full-structure
+
+# Debouncing en milisegundos
+WATCH_DEBOUNCE_MS=1000
+
+# Polling interval (en lugar de eventos nativos)
+WATCH_POLL_INTERVAL=100
+
+# Auto upload cuando se detecten cambios
+WATCH_AUTO_UPLOAD=true
+
+# Tamaño de batch para uploads
+WATCH_BATCH_SIZE=10
+
+# Patrones a ignorar
+WATCH_IGNORE_PATTERNS=node_modules,\.git,\.env
+
+# Detectar tipos de documento automáticamente
+WATCH_AUTO_DETECT=false
+
+# Organizar automáticamente
+WATCH_AUTO_ORGANIZE=false
+```
+
+---
+
+## 🧪 Plan de Testing Manual
+
+```bash
+# Test 1: Watch básico
+arela watch --directories ./test-folder --verbose
+
+# Test 2: Crear archivo en carpeta observada
+touch ./test-folder/test-file.pdf
+
+# Test 3: Modificar archivo
+echo "test content" >> ./test-folder/test-file.pdf
+
+# Test 4: Eliminar archivo
+rm ./test-folder/test-file.pdf
+
+# Test 5: Múltiples directorios
+arela watch --directories ./folder1,./folder2
+
+# Test 6: Dry run
+arela watch --directories ./test-folder --dry-run
+
+# Test 7: Configuración desde archivo
+arela watch --config ./watch-config.json
+```
+
+---
+
+## 🚀 Próximos Pasos
+
+1. ✅ **Revisar y ajustar este plan** con feedback del equipo
+2. **Crear estructura de archivos** base
+3. **Implementar Fase 1** (Fundaciones)
+4. **Testing incremental** después de cada fase
+5. **Documentación** mientras se avanza
+
+---
+
+## 📚 Referencias Útiles
+
+- **Chokidar Docs**: https://github.com/paulmillr/chokidar
+- **Node.js fs.watch vs fs.watchFile**: Node.js official docs
+- **Debouncing**: https://github.com/lodash/lodash/blob/master/debounce.js
+
+---
+
+**Versión del Plan**: 1.0  
+**Fecha**: Hoy  
+**Estado**: 🟢 Listo para Implementación