johanleroy
9390b62249
Installer une nouvelle version remplace les fichiers sur disque mais ne touche
pas le process en cours : l'ancienne instance gardait le port 7317, la version
fraîchement installée mourait sur EADDRINUSE avant son handshake, et le shell se
contentait d'un console.error suivi d'un app.quit(). Depuis le lanceur, cliquer
l'icône ne produisait donc rien du tout.
- Tout échec de démarrage ouvre un dialogue Retry / Show log / Quit
(start-failure.ts, texte pur et testé) et la sortie du daemon est conservée
dans <userData>/logs/daemon.log. Une mort du daemon APRÈS le handshake propose
de le relancer, au lieu de laisser une fenêtre morte à l'écran.
- Le port est diagnostiqué avant le spawn (port-guard.ts, empreinte
{pid, ownerPid, port}) : un daemon orphelin, dont l'Electron est mort, est
repris (SIGTERM puis SIGKILL, en attendant un bind réellement possible) ;
une instance vivante ou un tiers (service, npx) est annoncé avec l'action qui
débloque, et jamais tué. La reprise exige deux preuves, l'empreinte orpheline
ET l'identité du process (ps -ww), car un pidfile périmé peut désigner un pid
recyclé entre-temps par un programme quelconque.
- Une mise à jour installée à chaud est signalée avec « Restart now »
(upgrade-watch.ts), qui arrête le daemon avant app.relaunch() ; sans quoi le
lock d'instance unique renvoyait silencieusement sur la fenêtre de l'ancienne
version, et on croyait avoir migré.
- ARBORETUM_DESKTOP_PORT pour cohabiter avec un Arboretum qui occupe 7317 en
permanence (service installé, ou daemon lancé en terminal).
24 tests dans packages/desktop/test, et quatre scénarios rejoués en dev sous
xvfb-run avec profil isolé : port tenu par un tiers, orphelin repris puis SPA
servie, instance vivante laissée intacte, pid recyclé épargné.
156 lines
8.2 KiB
Markdown
156 lines
8.2 KiB
Markdown
# 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.
|