johanleroy
63f2697745
CI / Build & test (Node 22) (push) Successful in 11m12s
CI / Build & test (Node 24) (push) Successful in 10m14s
CI / No em/en dashes (push) Successful in 3s
Deploy site (production) / build-and-deploy (push) Successful in 19s
CI / Pack & boot smoke (Node 22) (push) Has been cancelled
Tout est additif : PROTOCOL_VERSION inchangé, aucune rupture d'API. Temps réel réellement armé - `pinSession` n'était appelé nulle part : une session vivante épingle désormais le watcher FS de son worktree (`WorktreeManager.syncSessionPin` + `resolveWorktreeForCwd`), donc un worktree où un agent écrit se rafraîchit même si personne ne le regarde (mesuré ~350 ms). - Les abonnements `watch` sortent de `GitPanel`, démonté dès qu'on quitte son onglet, ce qui coupait le seul abonnement de toute l'app : `composables/useWatchedWorktrees.ts` (monté dans App.vue) suit le worktree actif et les dépôts dépliés, borné à 40. - Une coupure WS ne laisse plus l'UI sur des listes périmées : rechargement complet au retour. - `worktree_changes` alimente `worktrees.changeVersion`, consommé par l'arbre de fichiers, le diff (son `:version` était câblé à 0) et l'éditeur, qui recharge un tampon propre ou lève la bannière de conflit avant la sauvegarde au lieu d'attendre le 409. Corrélation session ↔ worktree par contenance (`@arboretum/shared/path-match.ts`) - Un terminal lancé dans un sous-répertoire (« Démarrer le projet ») ou une session de groupe reliée par `--add-dir` apparaissent enfin sous leur worktree ; le worktree le plus spécifique gagne. - Règle unique partagée par le daemon, le web et l'extension. Historisation - `commitLog` / `commitDiff` purs, `GET /repos/:id/worktrees/log` et `diff?commit=` (hash strictement validé, mêmes bornes que les diffs de fichiers). - `CommitHistory.vue` sous le panneau Git : commits, marquage des non poussés, diff déplié sur place. Visibilité - Compteurs git complets sur chaque worktree de l'arbre et du panneau Groupes (ils n'existaient qu'en barre de statut, pour le seul worktree actif), avec upstream et dernier commit en infobulle ; `locked`, `prunable` et un dépôt invalide sont désormais visibles. - Le panneau Groupes montre sa composition réelle (dépôts, worktrees, sessions) et teinte l'explorateur. Polish visuel - Les toasts d'erreur, persistants, s'empilaient derrière les modals : téléportés au-dessus. - Sur mobile, ouvrir un terminal ou changer d'activité n'avait aucun effet visible. - Tailles de panneaux clampées sur la fenêtre, barres d'onglets sans scrollbar parasite, états de chargement et d'erreur dans les trois panneaux, accessibilité des 11 modals centralisée dans ModalHost, splitters au clavier, numéros de diff collants, `window.confirm` remplacé. Windows (daemon et packaging) - `where.exe`, PowerShell comme shell de lancement, askpass `.cmd` (clone/push HTTPS par PAT), `taskkill /T`, `%APPDATA%`, `arboretum install` via tâche planifiée. - Scripts de build exécutables sur un hôte Windows (`npm.cmd`, extraction sans `unzip` ni `bash`). - Job CI `windows-latest` conditionné par ENABLE_WINDOWS_BUILD ; procédure runner dans docs/CI_RUNNERS.md. Logo Debian : cause racine - Une icône unique de 895×895 atterrissait dans `hicolor/895x895`, répertoire absent d'`index.theme` donc ignoré par la spécification freedesktop ; et `executableName` dérivait du nom scopé du paquet (`@arboretumdesktop`). Jeu d'icônes standard généré + `executableName: arboretum`, plus `deb.synopsis` (description courte vide dans apt) et `Section: devel`. - Runtime Node embarqué élagué : 205 → 118 Mo. - Auto-update réparé : la release flottante `desktop-latest` que les binaires interrogent n'existait pas. Doc et vitrine - README/README.fr : installation par plateforme, mode serveur web (nginx, LAN), dépannage, variables d'environnement, flags manquants. - Doc in-app réécrite (elle renvoyait aux pages Worktrees et Sessions supprimées). - Section « Accès distant » dans les Réglages ; le 403 BAD_ORIGIN nomme le flag à ajouter. - Site : prérequis et registre npm privé (le `npx` affiché renvoyait un 404), téléchargements réels par plateforme, section « trois façons de l'utiliser », navigation complétée, 16 clés i18n mortes purgées. Vérifications : 483 tests unitaires, 14 acceptances E2E vertes (dont p14/p15 nouvelles), captures de rendu sans erreur console (nouveau `verify-ui.mjs`), .deb reconstruit et contrôlé (icônes aux tailles standard, entrée .desktop valide).
118 lines
5.9 KiB
Markdown
118 lines
5.9 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.
|
||
|
||
## 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.
|