# 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 is asked to stop (`SIGTERM` on POSIX, `taskkill /T` on Windows, which
   Windows requires to take the whole process tree down rather than leaving PTY grandchildren behind).

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

**Must be built on a Windows host.** Cross-building from Linux (including via Wine) does not work, and
the option has been removed from this document to stop people losing time on it:

- `node-pty`'s `check-prebuild.js` exits successfully as soon as the *host* binary exists, so
  `prebuild-install` never runs and no win32 binary is fetched (its published tarball only ships
  `prebuilds/linux-*`);
- its `post-install.js` copies `conpty.dll` and `OpenConsole.exe` **only when the build platform is
  win32**. Without them there is no ConPTY, hence no terminal at all.

In CI this is a dedicated job on a `windows-latest` runner, enabled by the `ENABLE_WINDOWS_BUILD`
repository variable. Full procedure to register such a runner: [`docs/CI_RUNNERS.md`](../../docs/CI_RUNNERS.md).

The app requires Windows 10 1809+ (ConPTY). The installer is not code-signed, so SmartScreen shows
"unknown publisher": choose "More info" then "Run anyway".

### macOS (best-effort)

Build on a Mac (`dmg`/`zip` cannot be produced elsewhere); there is no macOS runner, so it is a manual
step. 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`.

## What the shell adds beyond the window

- **Tray icon** (`src/main/tray.ts`): open the window, toggle launch-at-login, quit. On macOS it uses a
  monochrome *template* image so it follows the menu-bar theme.
- **Application menu** (`src/main/app-menu.ts`): required on macOS, where without it ⌘C / ⌘V / ⌘A are not
  bound anywhere in the app. Closing the window hides it; `app.on('activate')` brings it back from the Dock.
- **Launch at login** (`src/main/autostart.ts`): a `.desktop` file under `~/.config/autostart` on Linux,
  `app.setLoginItemSettings` on Windows/macOS.
- **Auto-update** (`src/main/updater.ts`): see below.
- **PATH enrichment** (`src/main/env.ts`): a GUI app starts with a minimal PATH. On POSIX we add
  `/usr/local/bin`, `/opt/homebrew/bin`, `~/.local/bin`; on Windows `%LOCALAPPDATA%\Programs` and
  `%APPDATA%\npm`, where the Claude CLI and global npm binaries actually live.

## Startup, and what happens when it fails

The shell owns the daemon: it spawns it on **port 7317** (`ARBORETUM_DESKTOP_PORT` overrides), waits for
the handshake on fd 3, seeds the session cookie, then loads the SPA. Since a fixed port is easy to hold
hostage, the port is checked *before* spawning (`src/main/port-guard.ts`) and the outcome decides:

| Who holds the port | What the app does |
| --- | --- |
| Nobody | Starts normally. |
| **Our own daemon, orphaned** (its Electron died: crash, `kill -9`, package upgrade) | Reclaims it: SIGTERM, then SIGKILL, waiting for the port to be *effectively* free, then starts. |
| **Another live instance** of the app | Says so, and points at the tray where that window is hiding. Never kills it. |
| A third party (`arboretum install` service, `npx @johanleroy/git-arboretum`, unrelated software) | Says so, and suggests stopping it or setting `ARBORETUM_DESKTOP_PORT`. |

Ownership is recorded in `<userData>/daemon/daemon.json` (`{pid, ownerPid, port}`): a live daemon whose
`ownerPid` is gone is an orphan, one whose owner is alive is another instance. Every failure now opens a
dialog with **Retry / Show log / Quit** instead of quitting silently, and the daemon's output is kept in
`<userData>/logs/daemon.log`. If the daemon dies *after* startup, the app offers to restart it rather
than leaving a dead window on screen.

`<userData>` is `~/.config/Arboretum` (Linux), `~/Library/Application Support/Arboretum` (macOS),
`%APPDATA%\Arboretum` (Windows).

## Installing a new version

Installers replace the files on disk; they never touch the running process. So after a `dpkg -i` (or an
NSIS run) **the open window keeps serving the old version**, and its daemon keeps port 7317 - which used
to make the freshly installed version unable to start at all.

The recommended order is therefore either one of:

1. Quit Arboretum from the tray, then install, then launch. Clean, nothing to think about.
2. Install while it runs, then click the launcher or the tray icon: the shell notices that its own
   binary changed on disk (`src/main/upgrade-watch.ts`) and offers **Restart now**, which stops the
   daemon before relaunching, so the new version finds its port free.

Answering *Later* keeps the old window; the prompt comes back only if yet another version is installed.
The check is inert in dev (`app.isPackaged` is false).

## Auto-update

electron-builder emits `latest*.yml` next to the artifacts and `electron-updater` reads them from a
**floating `desktop-latest` release** on Gitea, which the release workflow recreates on every version
(that URL is baked into shipped binaries, so it must always exist). Auto-update covers Windows (NSIS)
and Linux (AppImage); macOS updates are manual while the app is unsigned.

## Bundled Node runtime

`scripts/fetch-node.mjs` downloads a pinned Node (SHA256 verified) and **prunes it** to the binary and
its licence: headers, docs and `npm`/`corepack` are removed, since the daemon's dependencies are
installed at build time, never at runtime. That takes the embedded runtime from ~205 MB to ~118 MB.

## Icons

Generated by `python3 brand/build-assets.py` from the source logo, into `resources/`:

- `icons/{16,24,32,48,64,128,256,512}x*.png` : the Linux set, at **standard hicolor sizes**. This is not
  cosmetic: with a single non-standard size (the old 895×895), the directory is not declared in
  `hicolor/index.theme` and the freedesktop spec makes desktops ignore it, so the launcher showed no
  icon at all.
- `icon.png` (1024) : macOS source and generic fallback.
- `icon.ico` : Windows (NSIS installer and window).
- `trayTemplate.png` (+`@2x`) : monochrome macOS menu-bar icon.