From 45bad4c12bac733446c616f1ded91512bbfdcdb7 Mon Sep 17 00:00:00 2001 From: Bohdan Triapitsyn Date: Fri, 5 Jun 2026 23:58:43 +0300 Subject: [PATCH] docs: update desktop platform docs Document macOS and Windows desktop support Add Electron desktop development README Refresh contributing scripts and platform notes --- CONTRIBUTING.md | 76 +++++++++++++++++--- README.md | 35 +++++---- packages/electron/README.md | 140 ++++++++++++++++++++++++++++++++++++ 3 files changed, 228 insertions(+), 23 deletions(-) create mode 100644 packages/electron/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7777e41d..5a3d6c72 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,37 +10,91 @@ bun install ## Dev Scripts +Run commands from the project root unless a section says otherwise. + ### Web | Script | Description | Ports | |--------|-------------|-------| +| `bun run dev` | Default web HMR dev flow. | auto-selected dev ports | | `bun run dev:web:full` | Build watcher + Express server. No HMR — manual refresh after changes. | `3001` (server + static) | | `bun run dev:web:hmr` | Vite dev server + Express API. **Open the Vite URL for HMR**, not the backend. | `5180` (Vite HMR), `3902` (API) | +| `bun run start:web` | Start the packaged web server. | `3000` by default | Both are configurable via env vars: `OPENCHAMBER_PORT`, `OPENCHAMBER_HMR_UI_PORT`, `OPENCHAMBER_HMR_API_PORT`. ### Desktop (Electron) ```bash -bun run electron:dev +bun run electron:dev # HMR web UI + Electron shell +bun run electron:dev:bundled # Electron shell using built web assets +bun run electron:build # Package desktop app for the current platform ``` -Launches the Electron desktop shell in dev mode. +Desktop supports macOS and Windows. The build output is written to `packages/electron/dist`. + +macOS builds create `dmg` and `zip` files. You need Xcode/build tools for notarized packaging and icon asset work. + +Windows builds create an NSIS installer. If signing env vars are not set, the build script makes an unsigned installer. + +For desktop-specific details, see [`packages/electron/README.md`](./packages/electron/README.md). ### VS Code Extension ```bash -bun run vscode:dev # Watch mode (extension + webview rebuild on save) +bun run vscode:dev # Watch mode + Extension Development Host +bun run vscode:build # Build extension + webview +bun run vscode:package # Create a local .vsix package ``` -To test in VS Code: -```bash -bun run vscode:build && code --extensionDevelopmentPath="$(pwd)/packages/vscode" -``` +`bun run vscode:dev` opens an Extension Development Host automatically. You can override the editor or workspace with `OPENCHAMBER_VSCODE_BIN` and `OPENCHAMBER_VSCODE_DEV_WORKSPACE`. + +Example: `OPENCHAMBER_VSCODE_BIN=cursor bun run vscode:dev`. ### Shared UI (`packages/ui`) -No dev server — this is a source-level library consumed by other packages. During development, `bun run dev` runs type-checking in watch mode. +No standalone app server. This is a source-level library used by Web, Desktop, and VS Code. + +Useful package commands: + +```bash +bun run build:ui +bun run type-check:ui +bun run lint:ui +``` + +## Build And Package Commands + +| Command | What it does | +|---------|--------------| +| `bun run build` | Build all workspaces | +| `bun run build:web` | Build only `packages/web` | +| `bun run build:ui` | Build only `packages/ui` | +| `bun run build:electron` | Run Electron package build script without full packaging | +| `bun run electron:build` | Build packaged desktop app for the current OS | +| `bun run vscode:build` | Build the VS Code extension | +| `bun run vscode:package` | Package the VS Code extension as `.vsix` | +| `bun run pack:web` | Create a package archive for `@openchamber/web` | + +## Platform Build Notes + +You usually build desktop installers on the target platform. + +macOS: + +```bash +bun run electron:build +bun run release:test:intel +bun run release:test:arm +``` + +Windows: + +```bash +bun run electron:build +``` + +Linux is supported for web/CLI development. A Linux desktop app is still planned, so Electron packaging is mainly macOS and Windows right now. ## Before Submitting @@ -50,6 +104,12 @@ bun run lint # Must pass bun run build # Must succeed ``` +For docs-only changes, validation may be enough: + +```bash +bun run docs:validate +``` + ## Code Style - Functional React components only diff --git a/README.md b/README.md index 36a1c1d2..339fb124 100644 --- a/README.md +++ b/README.md @@ -58,13 +58,16 @@ - Background notifications plus reliable cross-tab session activity tracking - Built-in self-update + restart flow that keeps your server settings intact -### Desktop (macOS) +### Desktop (macOS + Windows) -- Native macOS menu integration with polished app actions and deep-link handling -- Multi-window support for parallel project/session workflows -- "Open In" shortcuts for Finder, Terminal, and your preferred editor -- Fast switching between local and remote instances -- Workspace-first startup flow with directory picker and steadier window restore behavior +- Floating Mini Chat: keep a small always-on-top assistant beside your editor, browser, or terminal +- Multiple native windows for separate projects or sessions +- Native notifications for task alerts while OpenChamber is hidden +- One-click open in VS Code, Cursor, Terminal, Finder, Explorer, and more +- Desktop host switcher for local and remote OpenChamber instances +- Convenient tunnel management without manual setup +- Deep-link connections for joining remote OpenChamber from a link +- SSH remote access with host import, connection management, and port forwarding ### VS Code Extension @@ -86,7 +89,7 @@ > **Prerequisite:** [OpenCode CLI](https://opencode.ai) installed. -### **Desktop (macOS)** +### **Desktop (macOS + Windows)** Download from [Releases](https://github.com/btriapitsyn/openchamber/releases). ### **VS Code** @@ -350,14 +353,16 @@ chown -R 1000:1000 data/
-Desktop (macOS) +Desktop (macOS + Windows) -- Connect to remote OpenChamber instances over SSH with dedicated lifecycle flows -- Project Actions: run dev servers, SSH port forwarding, open remote URLs locally -- Multi-window support for parallel project workflows -- "Open In" shortcuts for Finder, Terminal, and your preferred editor -- Fast switching between local and remote instances -- Native macOS menu, deep-link handling, and polished startup +- Floating Mini Chat: keep a small always-on-top assistant beside your editor, browser, or terminal +- Multiple native windows for separate projects or sessions +- Native notifications for task alerts while OpenChamber is hidden +- One-click open in VS Code, Cursor, Terminal, Finder, Explorer, and more +- Desktop host switcher for local and remote OpenChamber instances +- Convenient tunnel management without manual setup +- Deep-link connections for joining remote OpenChamber from a link +- SSH remote access with host import, connection management, and port forwarding
@@ -402,7 +407,7 @@ chown -R 1000:1000 data/ Active development. Here's what's being worked on or planned: -- Windows and Linux desktop apps +- Linux desktop app - Mobile app with remote instance and laptop connectivity - More built-in tunneling options - Kanban board for multi-agent management - keeping the human in the loop and in control diff --git a/packages/electron/README.md b/packages/electron/README.md new file mode 100644 index 00000000..d722c878 --- /dev/null +++ b/packages/electron/README.md @@ -0,0 +1,140 @@ +# OpenChamber Desktop + +Electron desktop runtime for OpenChamber on macOS and Windows. + +This package owns the native shell: windows, menus, deep links, native notifications, auto-updates, host switching, SSH connections, tunnel helpers, and packaged desktop builds. The web UI and OpenChamber server logic still live in `packages/web` and shared React UI lives in `packages/ui`. + +## How It Runs + +Desktop starts the OpenChamber web server in the same Electron main process. There is no separate sidecar subprocess for the OpenChamber server. + +`main.mjs` imports `@openchamber/web/server/index.js` and calls `startWebUiServer()`. The Electron window then loads the UI from the local server in development, or from packaged `resources/web-dist` assets in packaged builds. + +The preload bridge exposes desktop-only APIs to the web UI through `window.__OPENCHAMBER_DESKTOP__`. Privileged commands are checked in `main.mjs`, not only in the UI. + +## Main Files + +| File | Purpose | +|------|---------| +| `main.mjs` | Electron main process, app lifecycle, windows, menus, deep links, native IPC handlers, updates, local server startup | +| `preload.mjs` | Safe bridge from the rendered UI to Electron IPC | +| `ssh-manager.mjs` | SSH host import, connection lifecycle, tunnel/port forwarding helpers | +| `scripts/electron-dev.mjs` | Desktop dev launcher with Vite HMR support | +| `scripts/build-web-assets.mjs` | Builds `packages/web` and stages UI assets into `resources/web-dist` | +| `scripts/bundle-main.mjs` | Bundles Electron main code into `dist-bundle/main.mjs` for packaging | +| `scripts/rebuild-native.mjs` | Rebuilds native modules against the Electron runtime | +| `scripts/package.mjs` | Runs `electron-builder`, with unsigned Windows builds when signing env is missing | +| `resources/` | Packaged web assets, icons, and macOS entitlements | + +## Development + +From the repo root: + +```bash +bun install +bun run electron:dev +``` + +`bun run electron:dev` starts the web dev server with HMR, then launches Electron against `packages/electron/main.mjs`. + +Useful variants: + +```bash +bun run electron:dev:bundled +bun run type-check:electron +bun run lint:electron +``` + +`electron:dev:bundled` builds and uses packaged web assets instead of the HMR server. Use it when testing behavior closer to a packaged app. + +## Packaging + +From the repo root: + +```bash +bun run electron:build +``` + +That runs, in order: + +1. `build:web-assets` to build the web UI and copy it into `packages/electron/resources/web-dist`. +2. `bundle:main` to create `packages/electron/dist-bundle/main.mjs`. +3. `rebuild:native` to rebuild native modules for Electron. +4. `package.mjs` to run `electron-builder`. + +Build output goes to `packages/electron/dist`. + +macOS builds produce `dmg` and `zip` artifacts. Windows builds produce an NSIS installer. + +## Platform Notes + +macOS packaging needs Xcode/build tools for notarized builds and icon asset compilation. + +Windows packaging needs NSIS support through `electron-builder`. If no Windows signing env is set, `package.mjs` disables code signing and builds an unsigned installer. + +The package supports macOS and Windows desktop features. Some native discovery helpers are platform-specific. For example, app icon fetching and app filtering currently only work on macOS, while opening files in installed apps works on macOS and Windows. + +## Common Env Vars + +| Variable | Use | +|----------|-----| +| `OPENCHAMBER_ELECTRON_DEV=1` | Marks the runtime as desktop development mode | +| `OPENCHAMBER_ELECTRON_USE_BUNDLED_UI=1` | Uses staged web assets instead of the HMR dev server | +| `OPENCHAMBER_HMR_UI_PORT` | Preferred Vite UI port for desktop dev, default `5173` | +| `OPENCHAMBER_HMR_API_PORT` | Preferred API port for desktop dev, default `3901` | +| `OPENCHAMBER_RUNTIME=desktop` | Set by Electron before starting the web server | +| `OPENCHAMBER_DESKTOP_NOTIFY=true` | Enables desktop notification flow in the web server | +| `OPENCHAMBER_SKIP_API_COMPRESSION=true` | Defaulted by Desktop to reduce local CPU overhead | +| `OPENCODE_HOST` / `OPENCODE_PORT` / `OPENCODE_SKIP_START` | Connect Desktop to an external OpenCode server instead of starting one locally | + +## Native Features Owned Here + +- Floating Mini Chat windows. +- Multiple native windows. +- Native notifications. +- One-click open/reveal/open-in-app actions. +- Desktop host switcher and deep-link imports. +- Local and remote instance handling. +- SSH host import, connections, logs, and port forwarding. +- Tunnel lifecycle integration through the web server runtime. +- Auto-update checks, downloads, and restart/apply flow. + +## IPC Pattern + +Renderer code should call the desktop bridge exposed by `preload.mjs`. Do not import Electron from shared UI code. + +Add new native capabilities in this order: + +1. Add or update the `preload.mjs` bridge only if a new renderer-facing shape is needed. +2. Add the real command handling in `main.mjs` under `openchamber:invoke`. +3. Gate privileged commands in main process logic so remote pages cannot access local filesystem or shell capabilities. +4. Keep shared UI runtime contracts in `packages/ui` and server/runtime APIs in `packages/web` when the behavior is not inherently native. + +## Logs And Data + +Electron uses `electron-log`. In development, console logs are also visible in the terminal. In packaged apps, logs are written through the platform log path for the `OpenChamber` app name. + +Development builds use a separate user data directory named `OpenChamber Dev`, so dev state does not overwrite normal packaged app state. + +## Things To Be Careful With + +- Keep desktop-specific code in this package. Do not move OpenCode feature backend logic into Electron. +- Use hidden Windows process launches for background helpers. Avoid visible console flashes. +- Keep `@openchamber/web`, `bun-pty`, `node-pty`, and native modules external in `bundle-main.mjs`; bundling them can break Electron startup. +- Rebuild native modules after dependency or Electron version changes. +- Test both HMR dev mode and bundled UI mode when changing startup, preload, routing, or packaged asset behavior. + +## Quick Checks + +```bash +bun run type-check:electron +bun run lint:electron +bun run electron:dev:bundled +``` + +For full repo validation before shipping: + +```bash +bun run type-check +bun run lint +```