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.