Pandipipas/scoreko-electron-dev
1
0
Fork 0
mirror of https://github.com/Pandipipas/scoreko-electron-dev.git synced 2026-06-05 21:22:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #31 from Pandipipas/update-readme-for-new-scripts

Browse Source 
docs: translate README to English and remove refactor roadmap
This commit is contained in:
Pandipipas
2026-02-24 00:47:09 +01:00
committed by GitHub
parent ccea55ffa2 83f898bde6
commit fddf32905a
2 changed files with 36 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+36 -47
View File
@@ -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/<bundle>/dashboard/loading.html`) served by NodeCG while it starts.
- Loads the bundle dashboard at `http://localhost:<port>/bundles/<bundle>/<dashboard-route>`.
- 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`
docs/refactor-roadmap.md
-195
View File
@@ -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.