Translate Spanish text to English across docs and code

docs/refactor-roadmap.md

@@ -1,215 +1,195 @@
-# Roadmap de refactor, limpieza y mejoras (sin romper funcionalidad)
+# Refactor, cleanup, and improvement roadmap (without breaking functionality)
 
-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.
+This document outlines an improvement proposal for `scoreko-electron-dev`, prioritizing **zero regressions**. Each initiative includes a goal, concrete actions, and a safe implementation strategy.
 
-## 1) Arquitectura y organización del código
+## 1) Architecture and code organization
 
-### 1.1 Separar `main.ts` por responsabilidades
+### 1.1 Split `main.ts` responsibilities
 
-- **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.
+- **Current issue:** `src/main/main.ts` mixes configuration, UI, lifecycle, process management, error handling, and utilities.
+- **Actions:**
+  - Create `src/main/config/runtime-config.ts` for env var parsing.
+  - Create `src/main/nodecg/process-manager.ts` for `start/stop/wait-ready`.
+  - Create `src/main/windows/window-factory.ts` for window creation.
+  - Create `src/main/errors/error-presenter.ts` for logging + `dialog.showErrorBox`.
+- **Safe implementation:** move functions without changing behavior, cover with unit tests before modifying logic.
 
-### 1.2 Consolidar constantes de runtime
+### 1.2 Consolidate runtime constants
 
-- **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.
+- **Current issue:** URL and size constants are scattered.
+- **Action:** group them in `src/main/constants.ts` and type with `as const`.
+- **Benefit:** easier default tuning and review.
 
-### 1.3 Normalizar naming interno
+### 1.3 Improve naming
 
-- **Mejoras propuestas:**
-  - `runtimeConfig` → `appConfig`.
-  - `nodecgPath` → `nodecgRootPath`.
-  - `RUNTIME_NAME` → `NODE_RUNTIME_NAME`.
-- **Objetivo:** nombres más semánticos para mantenimiento.
+- **Goal:** more semantic names for maintainability.
 
-## 2) Robustez de proceso NodeCG
+## 2) NodeCG process robustness
 
-### 2.1 Endurecer validaciones de instalación
+### 2.1 Harden install validations
 
-- **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.
+- **Actions:**
+  - Validate read/write permissions in `lib/nodecg`.
+  - Validate whether the port is occupied before launching.
+  - Include more actionable diagnostics in error messages (exact suggested command).
+- **Safe implementation:** add opt-in validations with logs first, then convert to hard-fail.
 
-### 2.2 Mejorar el check de “ready”
+### 2.2 Improve the "ready" check
 
-- **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.
+- **Current issue:** readiness with `GET /` + `response.ok || 404` can give false positives.
+- **Actions:**
+  - Try a more explicit NodeCG endpoint if available.
+  - Otherwise add a check sequence with exponential retries + jitter.
 
-### 2.3 Control del shutdown más determinista
+### 2.3 More deterministic shutdown control
 
-- **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.
+- **Actions:**
+  - Add explicit state (`starting/running/stopping/stopped`).
+  - Avoid duplicate signals in `before-quit`, `will-quit`, and `process.exit` hooks.
+  - Record stop duration for diagnostics.
 
-## 3) Ventanas Electron y UX de carga
+## 3) Electron windows and loading UX
 
-### 3.1 Rework de loading flow
+### 3.1 Rework 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.
+- **Actions:**
+  - Avoid loading the main window too early if the dashboard fails.
+  - Add a specific timeout for `mainWindow.loadURL`.
+  - Include a friendly error-screen fallback inside Electron.
 
-### 3.2 Seguridad de navegación
+### 3.2 Navigation security
 
-- **Acciones:**
-  - Validar que `setWindowOpenHandler` y `will-navigate` permitan solo dominio esperado (`localhost:PORT`).
-  - Rechazar esquemas inseguros (`file:`, `javascript:`).
-- **Beneficio:** hardening del proceso principal.
+- **Actions:**
+  - Validate that `setWindowOpenHandler` and `will-navigate` only allow the expected domain (`localhost:PORT`).
+  - Keep external links in the default browser.
 
-### 3.3 Ajustes de resolución
+### 3.3 Resolution settings
 
-- **Mejora:** no fijar `minWidth/minHeight` a 1920x1080 en todos los escenarios.
-- **Propuesta segura:** usar valores por env var con defaults actuales para mantener compatibilidad.
+- **Improvement:** do not fix `minWidth/minHeight` at 1920x1080 for all scenarios.
+- **Safe proposal:** use env-var values with current defaults for compatibility.
 
-## 4) Configuración y variables de entorno
+## 4) Configuration and environment variables
 
-### 4.1 Validación tipada de env vars
+### 4.1 Typed env var validation
 
-- **Acciones:**
-  - Introducir esquema (`zod` o validación manual centralizada).
-  - Rechazar puertos fuera de rango.
-  - Marcar strings vacíos inválidos en rutas críticas.
+- **Actions:**
+  - Introduce a schema (`zod` or centralized manual validation).
+  - Reject out-of-range ports.
+  - Treat empty strings as invalid in critical paths.
 
-### 4.2 Documentación ejecutable
+### 4.2 Executable documentation
 
-- **Acciones:**
-  - Añadir `.env.example` con todos los defaults.
-  - Script de validación `npm run doctor` para detectar configuración inválida.
+- **Actions:**
+  - Add `.env.example` with all defaults.
+  - Add `npm run doctor` validation script to detect invalid configuration.
 
-### 4.3 Unificar defaults entre código y README
+### 4.3 Unify defaults between code and README
 
-- **Problema:** existe posible drift entre doc y runtime.
-- **Acción:** generar bloque de README automáticamente desde una fuente única de config.
+- **Current issue:** docs and runtime can drift.
+- **Action:** generate the README block automatically from a single config source.
 
-## 5) Build, packaging y distribución
+## 5) Build, packaging, and distribution
 
-### 5.1 Revisar iconos por plataforma
+### 5.1 Platform icon hardening
 
-- **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.
+- **Current issue:** `build.mac.icon` uses `.ico` (not ideal for macOS).
+- **Actions:**
+  - Use `.icns` for macOS.
+  - Keep `.ico` on Windows and set the correct icon set for Linux.
 
-### 5.2 Pipeline reproducible
+### 5.2 Reproducible pipeline
 
-- **Acciones:**
-  - Asegurar lockfile limpio y versión de Node fijada con `.nvmrc`.
-  - Añadir CI mínima (`typecheck`, build, smoke test).
+- **Actions:**
+  - Ensure a clean lockfile and pinned Node version with `.nvmrc`.
+  - Add minimal CI (`typecheck`, `build`, smoke test).
 
-### 5.3 Reducción de tamaño de artefacto
+### 5.3 Artifact size reduction
 
-- **Acciones:**
-  - Revisar qué se copia en `extraResources`.
-  - Excluir archivos no necesarios (logs, tests, cachés) en empaquetado.
+- **Actions:**
+  - Review what is copied in `extraResources`.
+  - Exclude unnecessary files (logs, tests, caches) in packaging.
 
-## 6) Calidad de código y testing
+## 6) Code quality and testing
 
-### 6.1 Añadir linting/formatting
+### 6.1 Add linting/formatting
 
-- **Acciones:**
-  - Configurar ESLint + Prettier.
-  - Reglas mínimas: imports ordenados, no variables no usadas, complejidad controlada.
+- **Actions:**
+  - ESLint + Prettier in scripts and CI.
+  - Minimum rules: sorted imports, no unused variables, controlled complexity.
 
-### 6.2 Unit tests para utilidades críticas
+### 6.2 Unit tests for critical utilities
 
-- **Cobertura objetivo inicial:**
-  - `parseEnvInt`, `getEnv`, `getOptionalEnv`.
-  - Resolución de icon path.
-  - Cálculo de delays y timeouts.
+- **Coverage target:**
+  - Env var parsing.
+  - Navigation allowlist.
+  - Icon path resolution.
+  - Delay and timeout calculation.
 
-### 6.3 Integration smoke tests
+### 6.3 Main bootstrap 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.
+- **Action:** test controlled Electron main startup with mocks (no real UI).
 
-## 7) Observabilidad y diagnóstico
+## 7) Observability and diagnostics
 
-### 7.1 Logger estructurado
+### 7.1 Structured logging
 
-- **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.
+- **Action:** replace `console.log` with leveled logger (`info/warn/error/debug`) and context.
+- **Benefit:** faster production debugging.
 
-### 7.2 Error codes y troubleshooting
+### 7.2 Error taxonomy
 
-- **Acciones:**
-  - Estandarizar errores con códigos (`E_NODECG_NOT_FOUND`, etc.).
-  - Añadir sección “Troubleshooting” en README con causas/soluciones.
+- **Actions:**
+  - Standardize errors with codes (`E_NODECG_NOT_FOUND`, etc.).
+  - Add a README troubleshooting section with causes/solutions.
 
-## 8) Limpieza técnica (deuda)
+## 8) Technical cleanup (debt)
 
-### 8.1 Eliminar lógica duplicada de cierre
+### 8.1 Remove duplicated shutdown logic
 
-- **Problema:** varios handlers llaman `stopNodeCG()`.
-- **Acción:** centralizar estrategia de parada en un solo coordinador.
+- **Action:** centralize stop strategy in a single coordinator.
 
-### 8.2 Extraer utilidades de proceso SO
+### 8.2 Platform-specific process utils
 
-- **Acción:** separar lógica Windows (`taskkill`) y POSIX (`process.kill`) en módulos específicos.
+- **Action:** split Windows (`taskkill`) and POSIX (`process.kill`) logic into dedicated modules.
 
-### 8.3 Revisar `shell: true` en spawn
+## 9) Suggested renames
 
-- **Motivo:** reducir superficie y comportamiento inesperado.
-- **Plan seguro:** introducir feature-flag para comparar comportamiento antes de retirar.
+- `waitForNodeCGReady` -> `waitForNodeCGHttpReady`
+- `stopNodeCG` -> `stopNodeCGProcess`
+- `createLoadingWindow` -> `createSplashWindow`
 
-## 9) Renombrados sugeridos (bajo riesgo)
+> Apply renames in atomic changes with tests to avoid breakages.
 
-- `loadingRoute` → `loadingDashboardRoute`.
-- `dashboardRoute` → `mainDashboardRoute`.
-- `baseUrl` → `nodecgBaseUrl`.
-- `launch()` → `launchApplication()`.
-- `stopNodeCG()` → `stopNodecgProcessGracefully()`.
+## 10) New files to create
 
-> Aplicar renombrados con cambios atómicos y tests para evitar breakages.
+- `docs/architecture.md` (module map and startup flow).
+- `docs/troubleshooting.md` (common failures + commands).
+- `src/main/errors/logger.ts`.
+- `src/main/main-controller.ts` (orchestrator for startup/shutdown).
 
-## 10) Qué crearía nuevo
+## 11) What to remove (if unused)
 
-- `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).
+- Legacy comments that describe behavior no longer present.
+- Duplicate icon-path legacy references if there is already one strategy.
 
-## 11) Qué eliminaría (si no se usa)
+## 12) Phase-based execution plan (without breaking anything)
 
-- 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.
+1. **Phase 0 – Safety baseline:** add tests for current behavior.
+2. **Phase 1 – Mechanical refactor:** move code to modules without changing behavior.
+3. **Phase 2 – Observability:** structured logs and clear errors.
+4. **Phase 3 – Hardening:** config validation, navigation security, and shutdown.
+5. **Phase 4 – Build/CI:** icon fixes, pipeline hardening, and smoke tests.
+6. **Phase 5 – Final cleanup:** renames and residual debt removal.
 
-> Eliminar solo tras comprobar uso real en CI y build local.
+## 13) Per-change acceptance criteria
 
-## 12) Plan de ejecución por fases (sin romper nada)
+- App still starts in dev and packaged mode.
+- Main dashboard loads after NodeCG readiness.
+- Controlled shutdown with no orphan NodeCG processes.
+- Unit and smoke tests pass.
 
-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.
+## 14) Recommended prioritization
 
-## 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.
+- **High:** process robustness, config validation, and deterministic shutdown.
+- **Medium:** observability, docs, and build hardening.
+- **Low:** cosmetic renames and package-size optimization.