electron

Electron Desktop App

Electron wrapper that packages NodeTool as a desktop application. Bundles the web editor and adds native features: system tray, file access, auto-updates.

Key folders:

• src/ - Main process and preload scripts
• assets/ - Icons and static resources
• resources/ - Templates bundled in app
• src/__tests__/ - Jest tests for the main process

Native Features

File explorer bridge: IPC handlers expose safe OS paths (HuggingFace cache, Ollama models) to renderer via window.api.openModelDirectory / openModelPath.

Development

npm run dev      # UI with hot reload
npm run build    # Compile renderer and main
npm start        # Start desktop app

Output in dist-electron/ for distribution.

Testing

Jest tests in src/__tests__/ cover the main process: IPC handlers, server spawning and watchdog, settings, the packaged-bundle verifier, window security, and the updater.

npm test              # Run the suite
npm run test:watch    # Watch mode
npm run test:coverage # With coverage
npm run check         # tsc + eslint + jest

There is no Playwright suite in this workspace — the Electron E2E tests were replaced with these Jest integration tests. Browser-level E2E lives in web/ (npm run test:e2e, npm run test:e2e-runner).

Server Management

Electron manages its own server. On launch (dev/production):

1. Detects Python environment (CONDA_PREFIX or settings)
2. Finds available port (starting 7777)
3. Starts server via Watchdog process manager
4. Monitors health, handles restarts

CI/CD

The Quality Gate's test-app leg runs the root npm run test, which includes this workspace's Jest suite (.github/workflows/quality-checks.yml).

GPU Detection

Electron uses torchruntime when a package needs a PyTorch-specific wheel index. This runs before installing or updating known torch-dependent packages such as nodetool-huggingface and nunchaku.

If no torch platform is cached, the package manager:

1. Installs torchruntime~=2.0 into the Python environment if needed
2. Detects the local GPU platform
3. Saves the result as TORCH_PLATFORM_DETECTED in ~/.config/nodetool/settings.yaml (or %APPDATA%/nodetool/settings.yaml on Windows)
4. Adds the matching PyTorch wheel index to the uv pip install command

If detection fails, it falls back to CPU wheels.

Supported torch platforms:

• NVIDIA CUDA: cu118, cu124, cu128, cu129
• AMD ROCm: rocm5.2, rocm5.7, rocm6.2, rocm6.4
• Apple Silicon: mps (uses the default PyPI index)
• CPU-only: cpu

Detection logs:

Detecting GPU platform before installing nodetool-huggingface...
Detecting GPU hardware...
Detected torch platform: rocm6.2 (GPUs: 1)
PyTorch index URL: https://download.pytorch.org/whl/rocm6.2

Failure falls back to CPU:

GPU detection failed: No GPUs found
Falling back to CPU-only installation

Building for Distribution

Standard Builds

From the repository root:

npm run build:packages
npm run build:web
npm run build:electron

From electron/:

npm run build        # Build and package for current platform
npm run dist         # Create distribution packages

Outputs to dist/ directory.

Local Non-Release Builds

The Electron build verifies that required Python wheels are published before packaging. For local test builds, you can skip this release-only registry check:

SKIP_PYTHON_REGISTRY_CHECK=1 npm run build:electron

or from electron/:

SKIP_PYTHON_REGISTRY_CHECK=1 npm run build

After packaging, verify the QuickJS WebAssembly asset is included with the externalized package:

find electron/dist -path "*/Resources/backend/node_modules/@jitl/quickjs-ng-wasmfile-release-sync/dist/emscripten-module.wasm" -print

Smoke-test the packaged app by running a nodetool.code.Code node:

return { ok: true, answer: 42 };

Linux Packaging

AppImage (default):

npm run dist         # Creates AppImage in dist/

Flatpak:

npm run dist         # Creates both AppImage and Flatpak

The Flatpak package provides sandboxed distribution for Linux with:

• Consistent runtime across distributions
• Automatic dependency management
• Easy installation via Flatpak

For detailed Flatpak information, see FLATPAK.md.

Supported Platforms

• Linux: AppImage, Flatpak
• macOS: DMG, ZIP (x64, arm64)
• Windows: NSIS installer