From a7cfd4fcedd5de32d380226ba93aa983985c9138 Mon Sep 17 00:00:00 2001 From: Matthew Horridge Date: Wed, 28 Jan 2026 13:26:52 -0800 Subject: [PATCH 1/3] Document Electron sidecar consumption Add a short README section describing how Electron should consume the sidecar artifacts and launch the service. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 579f0ac..80225eb 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,13 @@ Artifacts are built under: dist/sidecar// ``` +### Electron consumption (high level) + +Electron should consume the per-OS artifact produced by the packaging workflow, +unpack it into the app's bundled resources, and launch the sidecar binary at +runtime. The launcher sets `API_PORT` (and optionally `API_HOST`) and then polls +`/health/` before issuing API calls. + ## Serialization Format Harmonization rules and primitives serialize to JSON-friendly dictionaries with a consistent schema: From 9e910d6af8a9248998621f3d9cfee1b814203119 Mon Sep 17 00:00:00 2001 From: Matthew Horridge Date: Wed, 28 Jan 2026 15:26:54 -0800 Subject: [PATCH 2/3] Add Electron sidecar packaging guide Add a dedicated doc covering sidecar artifacts, placement, env vars, readiness, shutdown, and logging. --- docs/electron_sidecar.md | 65 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/electron_sidecar.md diff --git a/docs/electron_sidecar.md b/docs/electron_sidecar.md new file mode 100644 index 0000000..ce7504b --- /dev/null +++ b/docs/electron_sidecar.md @@ -0,0 +1,65 @@ +# Electron Sidecar Packaging & Launch Guide + +This document explains how to package, bundle, and launch the FastAPI sidecar +from an Electron app. It is intended for the Electron engineer integrating the +backend sidecar. + +## 1) What to package (per OS) +Use the GitHub Actions **Sidecar Packaging** workflow artifacts: + +- **macOS**: `harmonization-sidecar-mac` (tar.gz) +- **Windows**: `harmonization-sidecar-win` (zip) +- **Linux**: `harmonization-sidecar-linux` (tar.gz) + +Each artifact contains a PyInstaller **onedir** bundle: +``` +harmonization-sidecar/ + harmonization-sidecar[.exe] + _internal/ (runtime + dependencies) +``` + +Do **not** delete `_internal`. It is required at runtime. + +## 2) Where to place it in the Electron app +Unpack into your app resources, e.g.: +``` +/resources/sidecar// + harmonization-sidecar/ + harmonization-sidecar(.exe) + _internal/ +``` + +## 3) How to launch the sidecar (env + process) +The launcher must set environment variables and then spawn the binary. + +**Required env vars** +- `API_PORT` (required): port chosen by the launcher +- `API_HOST` (optional): defaults to `127.0.0.1` +- `API_LOG_PATH` (optional): file path for logs in addition to stdout/stderr + +**How Electron sets env vars and starts the process** +Electron’s main process uses Node.js process APIs. To pass env vars, use +`child_process.spawn()` (or similar) and pass an `env` object that extends +`process.env`. This is standard Node.js behavior; see the Node.js `child_process` +documentation for details. citeturn0search6 + +Note: On Windows, environment variable keys are case-insensitive. Avoid +duplicating keys with different casing (e.g., `PATH` vs `Path`). citeturn0search6 + +## 4) Readiness +After spawn, poll: +``` +GET http://127.0.0.1:/health/ +``` +Ready when HTTP 200 is returned. + +## 5) Shutdown +Preferred: +``` +POST http://127.0.0.1:/shutdown/ +``` +Fallback: terminate the process (SIGTERM on mac/Linux, CTRL_BREAK on Windows). + +## 6) Logging +Logs are JSON lines to stdout/stderr (capturable by Electron). Optionally set +`API_LOG_PATH` to write logs to a file. From 8893239f96151efe6a6bd4b8a446a69d0e6c6527 Mon Sep 17 00:00:00 2001 From: Matthew Horridge Date: Wed, 28 Jan 2026 15:28:59 -0800 Subject: [PATCH 3/3] Link Electron sidecar guide in README Add a pointer to docs/electron_sidecar.md from the Electron consumption section. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 80225eb..0289d0d 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,8 @@ unpack it into the app's bundled resources, and launch the sidecar binary at runtime. The launcher sets `API_PORT` (and optionally `API_HOST`) and then polls `/health/` before issuing API calls. +See `docs/electron_sidecar.md` for the full packaging and launch guide. + ## Serialization Format Harmonization rules and primitives serialize to JSON-friendly dictionaries with a consistent schema: