# 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

```bash
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.

```bash
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.