scoreko-electron-dev/docs/refactor-roadmap.md

# Roadmap de refactor, limpieza y mejoras (sin romper funcionalidad)

Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` priorizando **cero regresiones**. Cada iniciativa incluye objetivo, acciones concretas y estrategia de implementación segura.

## 1) Arquitectura y organización del código

### 1.1 Separar `main.ts` por responsabilidades
- **Problema actual:** `src/main/main.ts` concentra configuración, UI, lifecycle, gestión de procesos, manejo de errores y utilidades.
- **Acciones:**
  - Crear `src/main/config/runtime-config.ts` para parseo de env vars.
  - Crear `src/main/nodecg/process-manager.ts` para `start/stop/wait-ready`.
  - Crear `src/main/windows/window-factory.ts` para creación de ventanas.
  - Crear `src/main/errors/error-presenter.ts` para logging + `dialog.showErrorBox`.
- **Riesgo:** bajo, si se conserva API interna por pasos.
- **Implementación segura:** mover funciones sin cambiar lógica, cubrir con tests unitarios antes de modificar comportamiento.

### 1.2 Consolidar constantes de runtime
- **Problema actual:** constantes de URLs y tamaños están dispersas.
- **Acciones:** agrupar en `src/main/constants.ts` y tiparlas con `as const`.
- **Beneficio:** facilita ajuste de defaults y revisiones.

### 1.3 Normalizar naming interno
- **Mejoras propuestas:**
  - `runtimeConfig` → `appConfig`.
  - `nodecgPath` → `nodecgRootPath`.
  - `RUNTIME_NAME` → `NODE_RUNTIME_NAME`.
- **Objetivo:** nombres más semánticos para mantenimiento.

## 2) Robustez de proceso NodeCG

### 2.1 Endurecer validaciones de instalación
- **Mejoras:**
  - Validar permisos de lectura/escritura en `lib/nodecg`.
  - Validar si el puerto está ocupado antes de lanzar.
  - Incluir diagnóstico más accionable en mensajes de error (comando sugerido exacto).
- **Implementación segura:** agregar validaciones opt-in primero con logs, luego convertir a hard-fail.

### 2.2 Mejorar el check de “ready”
- **Problema:** readiness actual con `GET /` + `response.ok || 404` puede dar falsos positivos.
- **Acciones:**
  - Intentar endpoint más explícito de NodeCG si existe.
  - Si no existe, añadir secuencia de checks con retries exponenciales + jitter.
- **Compatibilidad:** mantener fallback al check actual inicialmente.

### 2.3 Control del shutdown más determinista
- **Acciones:**
  - Añadir estado explícito (`starting/running/stopping/stopped`).
  - Evitar dobles señales en hooks `before-quit`, `will-quit`, `process.exit`.
  - Registrar duración de parada para diagnósticos.

## 3) Ventanas Electron y UX de carga

### 3.1 Rework de loading flow
- **Mejoras:**
  - Evitar cargar la ventana principal demasiado pronto si falla dashboard.
  - Añadir timeout específico para `mainWindow.loadURL`.
  - Incluir fallback de pantalla de error amigable dentro de Electron.

### 3.2 Seguridad de navegación
- **Acciones:**
  - Validar que `setWindowOpenHandler` y `will-navigate` permitan solo dominio esperado (`localhost:PORT`).
  - Rechazar esquemas inseguros (`file:`, `javascript:`).
- **Beneficio:** hardening del proceso principal.

### 3.3 Ajustes de resolución
- **Mejora:** no fijar `minWidth/minHeight` a 1920x1080 en todos los escenarios.
- **Propuesta segura:** usar valores por env var con defaults actuales para mantener compatibilidad.

## 4) Configuración y variables de entorno

### 4.1 Validación tipada de env vars
- **Acciones:**
  - Introducir esquema (`zod` o validación manual centralizada).
  - Rechazar puertos fuera de rango.
  - Marcar strings vacíos inválidos en rutas críticas.

### 4.2 Documentación ejecutable
- **Acciones:**
  - Añadir `.env.example` con todos los defaults.
  - Script de validación `npm run doctor` para detectar configuración inválida.

### 4.3 Unificar defaults entre código y README
- **Problema:** existe posible drift entre doc y runtime.
- **Acción:** generar bloque de README automáticamente desde una fuente única de config.

## 5) Build, packaging y distribución

### 5.1 Revisar iconos por plataforma
- **Problema:** en `build.mac.icon` se usa `.ico` (no ideal para macOS).
- **Acciones:**
  - Usar `.icns` en macOS.
  - Mantener `.ico` en Windows y set icon set correcto para Linux.
- **Estrategia segura:** fallback conservando lo actual hasta tener assets definitivos.

### 5.2 Pipeline reproducible
- **Acciones:**
  - Asegurar lockfile limpio y versión de Node fijada con `.nvmrc`.
  - Añadir CI mínima (`typecheck`, build, smoke test).

### 5.3 Reducción de tamaño de artefacto
- **Acciones:**
  - Revisar qué se copia en `extraResources`.
  - Excluir archivos no necesarios (logs, tests, cachés) en empaquetado.

## 6) Calidad de código y testing

### 6.1 Añadir linting/formatting
- **Acciones:**
  - Configurar ESLint + Prettier.
  - Reglas mínimas: imports ordenados, no variables no usadas, complejidad controlada.

### 6.2 Unit tests para utilidades críticas
- **Cobertura objetivo inicial:**
  - `parseEnvInt`, `getEnv`, `getOptionalEnv`.
  - Resolución de icon path.
  - Cálculo de delays y timeouts.

### 6.3 Integration smoke tests
- **Acción:** test que verifique arranque controlado de Electron main con mocks (sin UI real).
- **Objetivo:** detectar regresiones de lifecycle y cierre de NodeCG.

## 7) Observabilidad y diagnóstico

### 7.1 Logger estructurado
- **Acción:** reemplazar `console.log` por logger con niveles (`info/warn/error/debug`) y contexto.
- **Beneficio:** depuración más rápida en producción.

### 7.2 Error codes y troubleshooting
- **Acciones:**
  - Estandarizar errores con códigos (`E_NODECG_NOT_FOUND`, etc.).
  - Añadir sección “Troubleshooting” en README con causas/soluciones.

## 8) Limpieza técnica (deuda)

### 8.1 Eliminar lógica duplicada de cierre
- **Problema:** varios handlers llaman `stopNodeCG()`.
- **Acción:** centralizar estrategia de parada en un solo coordinador.

### 8.2 Extraer utilidades de proceso SO
- **Acción:** separar lógica Windows (`taskkill`) y POSIX (`process.kill`) en módulos específicos.

### 8.3 Revisar `shell: true` en spawn
- **Motivo:** reducir superficie y comportamiento inesperado.
- **Plan seguro:** introducir feature-flag para comparar comportamiento antes de retirar.

## 9) Renombrados sugeridos (bajo riesgo)

- `loadingRoute` → `loadingDashboardRoute`.
- `dashboardRoute` → `mainDashboardRoute`.
- `baseUrl` → `nodecgBaseUrl`.
- `launch()` → `launchApplication()`.
- `stopNodeCG()` → `stopNodecgProcessGracefully()`.

> Aplicar renombrados con cambios atómicos y tests para evitar breakages.

## 10) Qué crearía nuevo

- `docs/architecture.md` (mapa de módulos y flujo de inicio).
- `docs/troubleshooting.md` (errores comunes).
- `.env.example` (variables documentadas y defaults).
- `scripts/doctor.mjs` (chequeo preflight).
- `tests/main/*.test.ts` (suite base de utilidades y lifecycle).

## 11) Qué eliminaría (si no se usa)

- Configuraciones o scripts redundantes de rebuild nativo cuando no sean necesarios para el bundle actual.
- Referencias legacy de rutas de iconos duplicadas si ya hay estrategia única.

> Eliminar solo tras comprobar uso real en CI y build local.

## 12) Plan de ejecución por fases (sin romper nada)

1. **Fase 0 – Baseline:** typecheck + build + smoke manual.
2. **Fase 1 – Refactor mecánico:** mover código a módulos sin cambiar comportamiento.
3. **Fase 2 – Tests:** cubrir utilidades y lifecycle.
4. **Fase 3 – Hardening:** validación de config, seguridad de navegación y shutdown.
5. **Fase 4 – Packaging:** iconos por plataforma y CI.
6. **Fase 5 – Limpieza final:** renombrados y eliminación de deuda residual.

## 13) Criterios de aceptación por cambio

- `npm run typecheck` en verde.
- `npm run build` en verde.
- Arranque correcto mostrando loading y luego dashboard.
- Cierre correcto sin procesos huérfanos de NodeCG.
- Sin cambios visibles no intencionales en UX.

## 14) Priorización recomendada

- **Alta:** separación de módulos, tests base, hardening de shutdown y readiness.
- **Media:** validación tipada de env vars, logging estructurado, CI.
- **Baja:** renombrados cosméticos y optimización de tamaño de paquete.