docs: add detailed refactor and improvement roadmap

README.md

@@ -107,3 +107,7 @@ Además, firma el `.exe` con certificado (`CSC_LINK` / `CSC_KEY_PASSWORD` en `el
 - `build.linux.icon`
 - `SCOREKO_APP_USER_MODEL_ID`
 - `SCOREKO_APP_ICON_PATH`
+
+## Roadmap de refactor recomendado
+
+Si quieres una propuesta detallada de refactorización, limpieza y mejoras sin romper funcionalidad, revisa: `docs/refactor-roadmap.md`.

docs/refactor-roadmap.md

@@ -0,0 +1,192 @@
+# 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.