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

Refactor, cleanup, and improvement roadmap (without breaking functionality)

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) Architecture and code organization

1.1 Split main.ts responsibilities

• 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 Consolidate runtime constants

• 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 Improve naming

• Goal: more semantic names for maintainability.

2) NodeCG process robustness

2.1 Harden install validations

• 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 Improve the "ready" check

• 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 More deterministic shutdown control

• 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) Electron windows and loading UX

3.1 Rework loading flow

• 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 Navigation security

• Actions:
  • Validate that setWindowOpenHandler and will-navigate only allow the expected domain (localhost:PORT).
  • Keep external links in the default browser.

3.3 Resolution settings

• Improvement: do not fix minWidth/minHeight at 1920x1080 for all scenarios.
• Safe proposal: use env-var values with current defaults for compatibility.

4) Configuration and environment variables

4.1 Typed env var validation

• Actions:
  • Introduce a schema (zod or centralized manual validation).
  • Reject out-of-range ports.
  • Treat empty strings as invalid in critical paths.

4.2 Executable documentation

• Actions:
  • Add .env.example with all defaults.
  • Add npm run doctor validation script to detect invalid configuration.

4.3 Unify defaults between code and README

• Current issue: docs and runtime can drift.
• Action: generate the README block automatically from a single config source.

5) Build, packaging, and distribution

5.1 Platform icon hardening

• 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 Reproducible pipeline

• Actions:
  • Ensure a clean lockfile and pinned Node version with .nvmrc.
  • Add minimal CI (typecheck, build, smoke test).

5.3 Artifact size reduction

• Actions:
  • Review what is copied in extraResources.
  • Exclude unnecessary files (logs, tests, caches) in packaging.

6) Code quality and testing

6.1 Add linting/formatting

• Actions:
  • ESLint + Prettier in scripts and CI.
  • Minimum rules: sorted imports, no unused variables, controlled complexity.

6.2 Unit tests for critical utilities

• Coverage target:
  • Env var parsing.
  • Navigation allowlist.
  • Icon path resolution.
  • Delay and timeout calculation.

6.3 Main bootstrap smoke tests

• Action: test controlled Electron main startup with mocks (no real UI).

7) Observability and diagnostics

7.1 Structured logging

• Action: replace console.log with leveled logger (info/warn/error/debug) and context.
• Benefit: faster production debugging.

7.2 Error taxonomy

• Actions:
  • Standardize errors with codes (E_NODECG_NOT_FOUND, etc.).
  • Add a README troubleshooting section with causes/solutions.

8) Technical cleanup (debt)

8.1 Remove duplicated shutdown logic

• Action: centralize stop strategy in a single coordinator.

8.2 Platform-specific process utils

• Action: split Windows (taskkill) and POSIX (process.kill) logic into dedicated modules.

9) Suggested renames

• waitForNodeCGReady -> waitForNodeCGHttpReady
• stopNodeCG -> stopNodeCGProcess
• createLoadingWindow -> createSplashWindow

Apply renames in atomic changes with tests to avoid breakages.

10) New files to create

• 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).

11) What to remove (if unused)

• Legacy comments that describe behavior no longer present.
• Duplicate icon-path legacy references if there is already one strategy.

12) Phase-based execution plan (without breaking anything)

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.

13) Per-change acceptance criteria

• 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.

14) Recommended prioritization

• High: process robustness, config validation, and deterministic shutdown.
• Medium: observability, docs, and build hardening.
• Low: cosmetic renames and package-size optimization.