diff --git a/README.md b/README.md index edabdae..58429cf 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,53 @@ # scoreko-electron-dev -Electron wrapper to package a NodeCG installation that includes the `scoreko-dev` bundle, inspired by `opeik/runback-electron` but updated to modern Electron + TypeScript. +Desktop app (Electron + TypeScript) to run and package a NodeCG installation with the `scoreko-dev` bundle. -## Key requirements +## Requirements -- Node `>=22` (`.nvmrc` included). -- Electron pinned to `39.5.1`. +- Node.js `>=22` +- Dependencies installed with `npm install` -## What it does +## Available scripts -- Starts `lib/nodecg/index.js` as a child process from Electron. -- Shows the bundle loading dashboard route (`/bundles//dashboard/loading.html`) served by NodeCG while it starts. -- Loads the bundle dashboard at `http://localhost:/bundles//`. -- Packages NodeCG + assets inside the final app with `electron-builder`. +### Development -## Expected structure +- `npm run dev`: compiles in watch mode and opens Electron. +- `npm run watch`: TypeScript watch mode. +- `npm run dev:electron`: opens Electron when `dist/main/main.js` is ready. +- `npm run start`: full build and local run. -```text -scoreko-electron-dev/ -├─ lib/ -│ └─ nodecg/ -│ ├─ index.js -│ ├─ node_modules/ -│ └─ bundles/ -│ └─ scoreko-dev/ -├─ src/main/main.ts -├─ static/icons/ -└─ package.json -``` +### Build and distribution -## Scripts +- `npm run clean`: removes `dist` and `release`. +- `npm run typecheck`: validates types without emitting files. +- `npm run build`: compiles TypeScript and copies assets. +- `npm run pack`: generates the app without an installer (`electron-builder --dir`). +- `npm run dist:win`: builds a Windows installer. +- `npm run dist:linux`: builds a Linux AppImage. +- `npm run dist:mac`: builds a macOS package. +- `npm run dist:all`: builds artifacts for Windows, Linux, and macOS. -- `npm run dev`: development mode. -- `npm run build`: compile TypeScript and copy assets. -- `npm run start`: build and local run. -- `npm run test`: build + unit tests (`node:test`). -- `npm run doctor`: configuration/environment preflight (`lib/nodecg`, permissions, port, and env vars). -- `npm run lint`: minimal quality rules with ESLint. -- `npm run format`: format validation with Prettier. -- `npm run pack`: generate app without installer. -- `npm run dist`: generate installer. +### Quality and diagnostics -## Environment variables +- `npm run test`: build and tests (`node:test`). +- `npm run doctor`: environment/configuration diagnostics. +- `npm run lint`: lint with ESLint. +- `npm run lint:fix`: lint with auto-fix. +- `npm run format`: checks formatting with Prettier. +- `npm run format:write`: applies formatting with Prettier. -The **single source of truth for defaults** is in `.env.example`. +### Native modules -1. Copy `.env.example` to `.env` (or export variables in your shell/CI). -2. Adjust only what you need. -3. Run `npm run doctor` to validate configuration before starting. +- `npm run rebuild:native`: rebuilds NodeCG native modules. +- `npm run rebuild:better-sqlite3`: rebuilds only `better-sqlite3` for Electron. -## Cross-platform build (icons) +## Quick setup -- `build.win.icon`: `static/icons/icon.ico` -- `build.linux.icon`: `static/icons` -- `build.mac.icon`: `static/icons/icon.icns` +1. Copy `.env.example` to `.env`. +2. Adjust variables for your environment. +3. Run `npm run doctor` before developing or packaging. -> The `.icns` is referenced in build config and must exist locally to package macOS. +## References -## Troubleshooting and architecture - -- Troubleshooting guide: `docs/troubleshooting.md` -- Architecture map: `docs/architecture.md` -- Roadmap: `docs/refactor-roadmap.md` +- Troubleshooting: `docs/troubleshooting.md` +- Architecture: `docs/architecture.md` diff --git a/docs/refactor-roadmap.md b/docs/refactor-roadmap.md deleted file mode 100644 index 621c706..0000000 --- a/docs/refactor-roadmap.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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.