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.