Desktop-Backend und CLI anbinden

Local Backend & CLI Integration

Many developer-focused desktop applications combine a web UI, an embedded local backend server (Node.js + SQLite), and external command-line tools (git, claude, codex, gemini). Coordinate these layers so the user never has to manage ports, terminal environments, or orphaned daemons manually.

Embedded Local Server Lifecycle

1. Dynamic / Conflict-Free Port Binding:
   • Never hardcode a single port like 3000 or 4317 without fallback—if another process holds that port, the desktop app crashes on launch.
   • Bind to 127.0.0.1 on an ephemeral port (listen(0, '127.0.0.1') or probe from a preferred port upward), read server.address().port, and pass the bound port and per-session auth token to the desktop window via IPC/preload before loading the UI.
2. Readiness Handshake Before UI Navigation:
   • Wait for the embedded backend to finish SQLite migrations, skill discovery, and socket binding before resolving the window's initial startup state, displaying a lightweight native/splash loading state while booting.
3. Using Electron's Built-In Node Runtime for Child Scripts:
   • When an Electron app needs to spawn a pure Node.js child script on a user machine that does not have node installed globally, spawn process.execPath with env: { ...cleanEnv, ELECTRON_RUN_AS_NODE: '1' }.

External CLI Discovery, Preflight & Execution

1. Deterministic CLI Discovery:
   • Because macOS/Linux GUI apps do not inherit terminal .zshrc/.bashrc PATH exports, resolve the user's login shell PATH once at startup and check platform-standard installation paths:
     • macOS: /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, ~/.nvm/versions/node/*/bin, ~/.volta/bin, ~/.bun/bin
     • Windows: %APPDATA%\npm, %LOCALAPPDATA%\Programs, %ProgramFiles%\Git\cmd (where.exe / .cmd shim resolution)
2. Three-Step CLI Preflight (Binary $\rightarrow$ Version $\rightarrow$ Auth):
   • Verify each external CLI with a fast, non-interactive probe (--version and auth/status check with a 5-second timeout and stdin: 'ignore') and report structured status (missing, signed_out, ready) so the UI can guide installation or sign-in.
3. Non-Interactive Subprocess Execution:
   • Always pass { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true } (or a controlled stdin pipe closed immediately after input) so a CLI prompting for [y/N] or credentials never hangs silently in the background.
   • Stream stdout and stderr line-by-line with bounded ring buffers so a verbose CLI output cannot exhaust main-process memory.