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

Session Handoff

Context

This handoff captures the agreed architecture direction for future refactor sessions. Do not restart architectural discovery from zero unless the codebase has changed substantially.

The previous analysis concluded that the codebase is fundamentally healthy. The refactor should be controlled and incremental, focused on lifecycle, updater safety, process shutdown, and explicit Electron security.

Current Technical State

Known validation from the prior analysis:

npm run typecheck
npm test
npm run lint

All passed at that time, with 42 tests passing.

Source Of Truth Documents

Use these documents in order:

1. docs/refactor/ARCHITECTURE_AUDIT.md
2. docs/refactor/ARCHITECTURE_RULES.md
3. docs/refactor/TARGET_ARCHITECTURE.md
4. docs/refactor/MIGRATION_PLAN.md
5. docs/refactor/SESSION_HANDOFF.md

High-Level Project Model

This is an Electron wrapper around a local NodeCG runtime.

Important facts:

• The app lives mostly in Electron main.
• There is no custom renderer.
• There is no preload.
• There is no meaningful IPC.
• Electron starts NodeCG locally.
• Electron loads dashboards from local HTTP origins.
• Runtime provisioning happens under Electron userData.
• NodeCG is launched through the Electron binary with ELECTRON_RUN_AS_NODE.

Do not treat the absence of IPC or preload as a missing feature. It is currently a desirable security property.

Preserve These Behaviors

• Runtime stored under userData.
• Relaunch after first runtime installation when required.
• Preservation of cfg, db, and logs.
• Use of ELECTRON_RUN_AS_NODE.
• Waiting for NodeCG HTTP readiness before dashboard load.
• Existing tests for config, provisioning, navigation, process management, and updates.
• Minimal Electron surface.
• No IPC unless required.

Main Risks To Address

Lifecycle

main.ts currently mixes:

• App configuration.
• Runtime preparation.
• Window handling.
• NodeCG startup.
• Readiness waiting.
• Update scheduling.
• Shutdown.

Refactor target:

• Introduce ApplicationController.
• Add explicit lifecycle states.
• Keep main.ts or bootstrap.ts thin.

Activation

Current risk:

• macOS activation can recreate a window and load a dashboard without proving NodeCG readiness.

Refactor target:

• Route activation through the same readiness-aware controller as startup.

Updater

Current risk:

• Remote JSON and asset URLs need stronger validation.
• Download and install behavior should be separated.
• Spanish text contains visible encoding corruption.

Refactor target:

• Rewrite updater internals in small modules.
• Validate metadata.
• Validate URLs.
• Use safe temporary paths.
• Fix encoding.

Process Shutdown

Current risk:

• Windows process-tree termination uses taskkill.
• It is low risk because the PID is numeric, but platform behavior should be isolated.

Refactor target:

• Add platform-process-killer.ts.
• Keep platform-specific commands out of NodeCG lifecycle orchestration.

Electron Security

Current strengths:

• nodeIntegration: false
• contextIsolation: true
• sandbox: true
• No preload.
• No IPC.

Refactor target:

• Add explicit webSecurity: true.
• Add permission denial by default.
• Add devtools policy by environment.
• Keep navigation allowlisted.

Recommended Next Session

Start with Phase 1 from MIGRATION_PLAN.md.

Immediate next work:

1. Add lifecycle tests around current behavior.
2. Cover first-run relaunch behavior.
3. Cover loading window and main window order.
4. Cover update scheduling.
5. Cover shutdown idempotency.
6. Cover activation readiness behavior.

Do not move files before these tests exist.

Important Constraints

• Do not re-architect around a renderer.
• Do not introduce IPC proactively.
• Do not rewrite the whole project.
• Do not move folders before preserving behavior with tests.
• Do not remove the managed NodeCG runtime strategy.
• Do not delete user-owned runtime directories.
• Do not broaden Electron permissions.

Preferred Refactor Order

1. Tests around current lifecycle behavior.
2. Pure path and URL extraction.
3. ApplicationController.
4. Shutdown service.
5. Updater rewrite.
6. Platform process-killer adapter.
7. Electron security hardening.
8. Script normalization.
9. Folder reorganization.

Completion Criteria For The Refactor

The refactor is successful when:

• Startup is controlled by a tested application controller.
• Shutdown is idempotent.
• Activation cannot load dashboards before NodeCG readiness.
• Updater metadata and URLs are validated.
• Downloads use safe paths and atomic finalization.
• Process-tree termination is isolated by platform.
• Browser windows declare secure settings explicitly.
• Permission requests are denied by default.
• No unnecessary IPC, preload, or renderer has been introduced.
• Typecheck, tests, and lint pass.

Reminder For Future Agents

This project does not need to become bigger to become safer.

Keep Electron small. Keep NodeCG ownership explicit. Keep remote update data untrusted. Keep the browser surface boring.