Orqestria Download
← Back to Electron and Vue foundation team

Skill · Version 1.0.0

Desktop backend and CLI integration

Coordinates an embedded server and external command-line tools so desktop startup and shutdown remain predictable.

local-backend-cli-integration

Team members using this skill

See how it helps

When is it useful?

Use when a desktop app depends on a local backend or tools installed outside its own bundle.

What does it help you do?

  • Uses conflict-free local binding and waits for backend readiness before loading the interface.
  • Finds executable paths in GUI environments and checks tool availability.
  • Owns subprocess lifetime, errors and cleanup instead of leaving background daemons.

Try asking this

Fix desktop startup when the preferred port is occupied and the CLI exists only in the user's login-shell path. Launch from the desktop without a terminal environment. Select an available port, verify backend readiness and show a useful error if the required executable is absent.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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.

Included files 1

  • SKILL.md