arboretum/packages/desktop/README.md

Arboretum Desktop

Native desktop shell (Electron) for Arboretum. It runs the existing daemon as a child process and shows its web UI in a window, already authenticated (no login screen). The heavy lifting stays in the daemon; this package is a thin shell (window lifecycle, daemon supervision, auto auth).

This package is intentionally outside the root npm workspaces so the daemon CI stays light. It has its own package-lock.json and is built on a developer machine (or a dedicated CI runner), not by the main npm run build.

How it works

1. The shell picks a data directory under the OS user-data path and spawns the bundled Node runtime running the packaged daemon (build/server/package/dist/index.js) with ARBORETUM_EMIT_TOKEN_FD=3.
2. The daemon mints a fresh token and writes {token, url} on file descriptor 3 (private stdio pipe).
3. The shell posts that token to /api/v1/auth/login from the window's session (server to server), which drops the arb_session cookie into the session jar, then loads the SPA on 127.0.0.1.
4. On quit, the daemon child gets SIGTERM (then SIGKILL after a grace delay).

A standalone Node runtime (pinned, >= 22.16) is bundled instead of reusing Electron's Node, so node:sqlite works without a flag and the node-pty prebuild keeps the node. ABI prefix.

Prerequisites (all platforms)

• Node >= 22.16 to build.
• git on PATH at runtime (worktree operations). claude is discovered on PATH or via the in-app Claude CLI setting; it is not bundled.

Develop

cd packages/desktop
npm install            # ELECTRON_SKIP_BINARY_DOWNLOAD=1 to skip the Electron binary if you only typecheck
npm run dev            # bundles main/preload, then `electron .` against the repo's built daemon

npm run dev runs the daemon from the repo (packages/server/dist, so run npm run build at the repo root first) using the system node.

Build installers

Each command builds the shell, prepares the daemon (npm pack + runtime deps with the right node-pty prebuild) and a standalone Node runtime, then runs electron-builder.

npm run dist:linux     # AppImage + .deb  (on Linux)
npm run dist:win       # NSIS + portable  (on Windows)
npm run dist:mac       # dmg + zip        (on macOS)

Artifacts land in packages/desktop/release/.

Linux

Fully supported. dist:linux runs on a Linux host or the Gitea CI runner.

Windows

Build on a Windows host (recommended): the node-pty win32 native binary and the installer (makensis) are most reliable there. Cross-building from Linux via Wine is a best-effort fallback. The app uses ConPTY (Windows 10 1809+). The installer is not code-signed yet, so SmartScreen shows "unknown publisher": choose "More info" then "Run anyway".

macOS (best-effort)

Build on a Mac (dmg/zip cannot be produced elsewhere). The app is not signed or notarized, so Gatekeeper blocks the first launch: right-click the app then "Open", or run xattr -dr com.apple.quarantine /Applications/Arboretum.app.

Auto-update

electron-builder emits latest*.yml next to the artifacts; electron-updater (wired in a later change) points at the Gitea release assets. Auto-update works for Windows (NSIS) and Linux (AppImage); macOS updates are manual while the app is unsigned.

Icon

resources/icon.png (square, >= 512px) is the single source; electron-builder derives every platform icon from it.