feat: complete pending roadmap items with doctor, hardening, and code quality

docs/architecture.md

@@ -0,0 +1,24 @@
+# Arquitectura del proceso principal
+
+## Flujo de arranque
+
+1. `src/main/main.ts` carga `appConfig` desde `config/runtime-config.ts`.
+2. Crea ventanas (`windows/window-factory.ts`).
+3. Arranca NodeCG con `nodecg/process-manager.ts`.
+4. Espera readiness HTTP y muestra loading -> dashboard principal.
+5. En cierre, ejecuta un único flujo de stop graceful para evitar procesos huérfanos.
+
+## Módulos principales
+
+- `config/runtime-config.ts`: lectura/validación de env vars.
+- `nodecg/process-manager.ts`: start, readiness y stop de NodeCG, validaciones de instalación/permisos/puerto.
+- `windows/window-factory.ts`: creación de ventanas y política de navegación.
+- `windows/navigation-security.ts`: allowlist de navegación interna y esquemas externos seguros.
+- `errors/error-presenter.ts`: presentación de errores fatales.
+- `errors/logger.ts`: logging estructurado (`info/warn/error/debug`).
+
+## Principios
+
+- Refactors mecánicos primero.
+- Hardening incremental con fallback conservador.
+- Validación automática por `typecheck`, `build`, `test`, `doctor`, `lint`.

docs/refactor-roadmap.md

@@ -5,6 +5,7 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 ## 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.
@@ -15,11 +16,13 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 - **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`.
@@ -29,6 +32,7 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 ## 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.
@@ -36,6 +40,7 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 - **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.
@@ -43,6 +48,7 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 - **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`.
@@ -51,41 +57,48 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 ## 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.
@@ -93,11 +106,13 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 - **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.
@@ -105,27 +120,32 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 ## 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.
@@ -133,13 +153,16 @@ Este documento detalla una propuesta de mejoras para `scoreko-electron-dev` prio
 ## 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.
 

docs/troubleshooting.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+## `No existe la carpeta NodeCG`
+
+- Verifica que exista `lib/nodecg`.
+- Asegúrate de que el proyecto contiene una instalación completa de NodeCG.
+
+## `Sin permisos de lectura/escritura sobre NodeCG`
+
+- Ajusta permisos de `lib/nodecg` para el usuario que ejecuta Electron.
+- En Linux/macOS: `chmod -R u+rw lib/nodecg` (según tu política local).
+
+## `El puerto <PORT> ya está en uso`
+
+- Libera el puerto o define `NODECG_PORT` en `.env`.
+- Usa `npm run doctor` para validar disponibilidad antes de arrancar.
+
+## `Timeout esperando NodeCG`
+
+- Revisa logs de NodeCG en la salida estándar.
+- Incrementa `NODECG_STARTUP_TIMEOUT_MS` si el entorno es lento.
+- Verifica dependencias de NodeCG (`cd lib/nodecg && npm install`).
+
+## Build macOS falla por icono
+
+- La configuración espera `static/icons/icon.icns`.
+- Crea ese archivo antes de ejecutar empaquetado para macOS.