Skip to content

The Craft Cloud desktop app and installers - #5

Merged
itrycodinganditsbad merged 17 commits into
mainfrom
desktop-app
Oct 19, 2026
Merged

itrycodinganditsbad merged 17 commits into
mainfrom
desktop-app

Conversation

@itrycodinganditsbad

@itrycodinganditsbad itrycodinganditsbad commented Oct 19, 2026 •

Copy link
Copy Markdown
Owner

craft-cloud is the Craft Cloud desktop app: a window plus a tray icon, for Windows, macOS and Linux. You join a cloud with a code, see whether the folder is in sync, add another computer (join string, QR code and a countdown), see and remove the account's computers, pause, and quit. The app only talks to the agent through craft-cloud-app and never touches the synced files. When no agent answers, the app starts it.

The app (apps/craft-cloud-desktop)

  • eframe/egui 0.36. The app's state is a pure model (Model::update(event) -> effects) behind an Agent trait, and the UI draws from it. Agent calls run on a worker thread, so the UI never waits on one.
  • Only one copy runs at a time. Starting a second brings the first window forward, even when it's hidden in the tray.
  • Tray: tray-icon on Windows and macOS. On Linux it's a StatusNotifierItem over zbus (ksni is under the Unlicense, which the licence gate refuses). It shows synced / syncing / offline / needs attention / paused, with Open, Open folder, Pause/Resume and Quit.
  • On Linux the tray is a process of its own (craft-cloud --tray), because Wayland can't hide a window. The window process exits when you close it. The tray registers whenever a StatusNotifierWatcher appears, so it comes back after a waybar restart.
  • The app adds its own start-at-login entry next to the agent's: the Run value Craft Cloud tray, ch.craftcloud.app.plist, or an XDG autostart entry for --tray.
  • Kittest snapshots of each screen.

Packaging (cargo xtask package)

  • Windows: craft-cloud-setup.exe (apps/craft-cloud-setup) installs per-user into %LOCALAPPDATA%\Programs\Craft Cloud and adds an Uninstall entry. --no-start-menu skips the Start-menu entry.
    • Before changing anything, it stops the running agent: it asks the agent to quit, then force-stops it after 60 s. If the agent still won't stop, it aborts with nothing changed.
    • It takes over start-at-login from an older install. Uninstalling keeps the synced folder and the data folder.
  • macOS: Craft Cloud.app (ch.craftcloud.app, unsigned), built in CI on macOS.
  • Linux: a tarball whose install.sh installs into ~/.local, and an uninstall.sh.

Agent changes

  • Start-at-login restarts the agent only after a crash:
    • "Needs you" states stay up and show in status.
    • When another agent holds the data folder, run exits 0.
    • The systemd unit gets RestartSec=30 and RestartPreventExitStatus=3.
    • The launchd entry gets ThrottleInterval 30.
  • One logger writes run.log for the background build and every start-at-login entry, rotated at 10 MiB.
  • The local API's status adds last_sync_ms and removed. Join can now refuse with folder_has_files. Both changes are backward-compatible.
  • A rate-limit refund only applies while the window it was counted in is current. Autostart ownership compares normalised paths. The signed-out hint names the app.
  • CI gets macos-latest.

Dependencies and licences

Every new crate here is one the other Craft apps already ship: eframe/egui 0.36, tray-icon 0.25 (as in the launcher), zbus (as in PhotoCraft), rfd, windows-registry, winresource, png and the QR code crate. The setup writes its Start-menu shortcut with Windows' own WScript.Shell.

The licence gate gets two named exceptions in xtask/src/licenses.rs and AGENTS.md. Both come with egui, which every Craft app ships:

  • BSL-1.0 for clipboard-win and error-code: eframe's clipboard on Windows.
  • OFL-1.1 and the Ubuntu Font Licence for egui's built-in fonts.

Testing

  • cargo xtask ci passes on Linux with 844 tests, and the sync and network simulations pass (seeds 0–15999 and 0–4999).
  • On Windows, clippy and 311 tests across the desktop, setup and agent crates pass, including the setup's real-registry test.
  • Installed on the author's Windows PC with the setup, over an agent that was syncing. The old agent quit cleanly and the new one carried on as the same device.
  • Installed on an Arch/Hyprland laptop from the tarball, over its systemd unit.
  • Not yet tried: anything on macOS beyond CI.

Left for later

  • Uninstalling from "Apps & features" can leave the program folder behind.
  • The packages don't ship the font and code licence texts yet.
  • install.sh has no way to skip the app-menu entry.
  • The single-instance files sit loose in the per-user data folder.
  • The D-Bus tray tests pass without running when dbus-daemon is missing.
  • If the agent is still mid-sync when install.sh's wait times out, the agent is left stopped.
  • The setup starts the new agent with its own output handles. When the setup runs from a pipe, it doesn't return.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz

itrycodinganditsbad and others added 17 commits October 19, 2026 01:20
…s from join codes

Restarts:
- A second `run` for a data folder another agent holds exits 0 with a one-line note (`cli::ran`), so a start at
  login racing the app's start is no failure.
- A problem only a person can put right found as `run` starts (a damaged or newer `account.json`, a damaged token)
  no longer ends it: the loop waits with the local API up, signed out, `run_state` `paused` with the reason. Every
  call but `logout` (forgets the account here) and `quit` is answered `needs_you`. The one exit 3 left from `run` is
  a data folder lock that isn't a regular file (no lock, so no local API either).
- The systemd unit gets `RestartSec=30` and `RestartPreventExitStatus=3`; the launch agent keeps
  `KeepAlive {SuccessfulExit: false}` and adds `ThrottleInterval 30`.

Logs:
- Every start-at-login entry runs `run --log`: the agent writes its output, its errors and every note that used to
  be an `eprintln!` (`runlog::note`) to `run.log` in the data folder, rotated at 10 MiB. The background build does
  the same for every command. launchd's own output goes to `launchd.log`.

The rest:
- The signed-out hint names the Craft Cloud app (or `join`), not the launcher.
- A rate-limit refund applies only in the window its attempt was counted in (`Limiter::count` returns it).
- Autostart ownership compares absolute paths with `.` and `..` resolved.
- The local API's status carries `last_sync_ms` and `removed` (the server refused this device), and a folder
  with files in it is answered `folder_has_files` (the app asks, then sends `adopt`).
- CI tests on macOS too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
A new app, `apps/craft-cloud-desktop` (binary `craft-cloud`), linking `craft-cloud-app` and `craft-cloud-proto`
only. No window yet: this is what the window will be a view of.

- `model`: the screens (starting, not running, join, joining, password needed, signed in, adding a computer,
  removed, error) and every way between them, as a pure `Model::update(event) -> Vec<Effect>`. Effects are agent
  calls, opening the folder, quitting the app and the app's own start-at-login entry, which follows the agent's
  and is only wanted where there is a tray. The failures say the spec's sentences.
- `agent`: an `Agent` trait with one method per `craft-cloud-app` call the app makes (`ClientAgent` finds the
  agent again whenever it is gone), and a `Link` that runs each call on a thread of its own and hands the answer
  back on a channel, plus a 2 s clock, so the UI thread never waits.
- `start_agent`: `craft-cloud-agent run --log` (`craft-cloud-agent-bg.exe` on Windows) from the app's own folder,
  detached and without a console window, then up to 5 s for it to answer.
- `single_instance`: a per-user file lock and a loopback port with a token, next to the agent's data folder; a
  second start asks the first to show its window and exits.

Tests: a model test per screen and per transition, a fake agent that goes away mid-session, joins with a pasted
link, spaces and lower case, a folder with files, an invite's password (matching, `weak_password`), an expired
code, no tray, and two instances in one test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The app's window on eframe/egui 0.36, about 420×560, resizable, light or dark with the OS, titled "Craft Cloud".

- `ui`: a view of the model per screen: starting; the join form (join string, folder with "Change…", this
  computer's name; "sync the files already there?" for a folder with files; "Joining…" that can't be sent twice);
  an invite's password, twice; signed in ("fabio on cloud.shadows.ch", online or offline, last sync, what the sync
  is doing, Open folder, Pause/Resume, Add a computer, the computers with Remove, none for this one, Sign out,
  Quit); add a computer (the join string, a QR code of its link, the 10-minute countdown, "waiting…" until
  "lptp1 joined"); removed; and problems as one line with Details.
- `app`: the model on eframe. `App::logic` (which eframe also calls while the window is hidden) takes the link's
  answers, the clock and outside events, and carries out effects; the folder picker (rfd: the OS's own dialog, the
  XDG portal on Linux) and the opener (`explorer`, `open`, `xdg-open`) run off the UI thread.
- Snapshots of every screen, drawn by kittest on wgpu against the fake agent and committed in `tests/snapshots/`
  (compared in the test with `image`; kittest's own snapshot feature brings an MPL-2.0 crate), and the buttons'
  events.

Licences: eframe always brings the Windows clipboard crates (`clipboard-win`, `error-code`: BSL-1.0) and egui's
fonts (`epaint_default_fonts`: OFL-1.1 and the Ubuntu Font Licence); both are named exceptions now, like Loro's.
QR codes come from `qrcodegen` (MIT). CI installs the window's headers and lavapipe on Linux.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The tray: synced, syncing, offline, needs attention or paused, from the 2 s status poll, with Open, Open folder,
Pause (Resume while paused) and Quit. Quit stops the agent too; the close button hides the window into the tray, or
ends the app where there is no tray (the agent keeps syncing).

- Windows and macOS: `tray-icon`, made on the event loop's thread.
- Linux: a StatusNotifierItem and its dbusmenu over the session D-Bus with zbus (pure Rust, MIT), only when an
  `org.kde.StatusNotifierWatcher` is on the bus (waybar, KDE, GNOME with the extension). `ksni`, which the design
  named, is under the Unlicense, which the licence gate refuses, so the item is served directly; its test runs a
  private `dbus-daemon` with a fake watcher (skipped where there is none).

The app's own start-at-login entry, hidden in the tray (`--hidden`), following the agent's `Status.autostart` and
only where there is a tray: the `Run` value `Craft Cloud tray` on Windows, `~/Library/LaunchAgents/
ch.craftcloud.app.plist` on macOS (no `KeepAlive`), `~/.config/autostart/craft-cloud.desktop` on Linux. Written by
pure functions into injectable roots, with golden files for a path with a space and an `ö`.

Icons: Craft Cloud's own cloud, drawn by `cargo xtask icons` (std only: shapes by coverage, PNG with a small deflate,
ICO and ICNS around the PNGs) into `apps/craft-cloud-desktop/assets/`, one tray icon per state; `cargo xtask ci`
checks they are current. The window uses the app icon.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
`cargo xtask package` makes release builds of the app and the agent and packs them for the OS it runs on into
`<target>/package/`, printing the package's path last.

- Windows: `craft-cloud-setup.exe`, a new crate `apps/craft-cloud-setup` with the three exes built in
  (`CRAFT_CLOUD_SETUP_PAYLOAD` and `include_bytes!`; without it the setup carries nothing and says so). It installs
  for this user into `%LOCALAPPDATA%\Programs\Craft Cloud` with no admin rights: it stops a running agent through
  its own `quit` and closes the app first, replaces the files, writes `HKCU\…\Uninstall\CraftCloud` (no
  Publisher; `UninstallString` calls its copy in the folder with `--uninstall`), adds a Start-menu shortcut unless
  `--no-start-menu` (a `.lnk` from `mslnk`), and starts the agent again if it ran. An older install in
  `Programs\craft-cloud` whose agent starts at login is moved: the new agent's `autostart on` takes the Run value
  over; the old files stay. It ends with "Open Craft Cloud now?", or quietly with `--quiet`. `--uninstall` stops the
  agent (also when it isn't running) and the app, removes their Run values where they start this install, the
  shortcut, the folder (after the setup ends, when it runs from there) and the key; the synced folder and the data
  folder stay. The exes get Craft Cloud's icon and a version resource (`winresource`).
- macOS: `Craft Cloud.app` (`ch.craftcloud.app`, `LSUIElement` false, the agent beside the app in
  `Contents/MacOS`, `Resources/icon.icns`), zipped with `ditto`; CI on macOS builds it as a check.
- Linux: `craft-cloud-<version>-linux-x86_64.tar.gz` with `install.sh` (into `~/.local/lib/craft-cloud`, links in
  `~/.local/bin`, a menu entry and icon; an upgrade stops and restarts the agent and points its start at login at
  the new copy) and `uninstall.sh` (quits the agent, `autostart off`, removes the app's login entry; the data and
  synced folders stay).

Tests: the setup's install, upgrade, move and uninstall against temporary folders and an in-memory registry, and
against the real registry under a throwaway key and the real shortcut writer on Windows; `install.sh` and
`uninstall.sh` in a temporary home.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
- README: installing the Craft Cloud app on Windows (the setup and its flags), macOS (the unsigned app) and Linux
  (the tarball's install.sh), joining with a code, the tray; the app in "How it fits together", the workspace and
  "Where things stand"; `cargo xtask package` and `icons`, and the window's snapshots, under "Building and testing".
- AGENTS.md: the app and the setup in the workspace map, `packaging/linux/`, xtask's new commands, and the layering:
  the app depends on `app` and `proto` only; the setup on nothing in the workspace (it uses the agent's command line).
- docs/design/live.md: `login` is the command line's now; the app joins with a code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
Between the agent's quit and the app's close, an open app showed "background service stopped" with Try again,
which would start the old agent again mid-install. The app now goes first, on install and on uninstall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The setup used to repeat the agent's `quit` for 30 s and carry on regardless. An agent still in a long pass kept
answering, so on BEAST the new agent's `autostart on` reached the old agent, which registered its own exe again,
and the setup still reported a move.

Now the setup asks the agent to quit through its local API (port, token and pid from `local-api.json`), waits up
to 60 s for its process to end, then ends it (the agent's writes are atomic, so that is safe) and checks it is
gone. A pid is only touched while it belongs to `craft-cloud-agent*.exe`. An agent that still can't be stopped
aborts the install, and the uninstall, before any file or registry value changes, saying so. Only then are the
files replaced, the Run value moved (read back: a value that doesn't start the new agent is a warning, not a
move), and the new agent started and waited for (5 s).

Tests: an agent that can't be stopped changes nothing on install or uninstall; a move whose `autostart on` is
answered by an old agent is reported as not moved; local-api.json reading (a token with a line break is refused);
the quit request's text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
An agent or app that was just stopped may hold its exe for a moment. The uninstall used to remove the "Apps &
features" entry first, then fail on such a file, which left a half-removed install with no way to finish it. Now
each removal is tried again for up to 10 s, and the Uninstall key goes last: if a file still can't go, the entry
stays, and running the uninstall again finishes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The refusal asked for the status but left the screen on "Joining…", which ignores a signed-in status, so the
spinner stayed for good. The form comes back now, and the status asked right then shows the signed-in view.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The icon showed its menu on a left click (as menu-bar items do) and the click handler opened the window as well.
The handler opens the window off macOS only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
When no agent answered, the app spawned `craft-cloud-agent run --log` itself. On lptp1 that agent ran outside
systemd: the unit's own start found the lock busy and exited 0, and a crash was never restarted. Where the
agent's systemd user unit exists, the app now runs `systemctl --user start craft-cloud-agent.service` and spawns
only if that fails (or without a unit, or off Linux).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
… stopped

install.sh gave up after a minute of `quit`s, and by then the agent had accepted the quit: it stopped after its
pass, exited 0, and with `Restart=on-failure` nothing started it again. Now the wait is up to 10 minutes
(`CRAFT_CLOUD_INSTALL_WAIT`), with a note after a few seconds. If it still runs out, nothing is installed and,
with the agent's systemd unit, `systemctl --user start` brings it back.

Tests: lptp1's upgrade with an agent that answers `quit` twice (the installed copy runs `autostart on` after the
copy, then `systemctl --user restart`), and the timeout (nothing installed, `systemctl --user start` called).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
…ds when closed

winit can't hide a window on Wayland, so on lptp1 the close was cancelled and the window never hid, and the
`--hidden` start at login showed it anyway. On Linux the app is now two processes:

- `craft-cloud --tray`: the tray only (the D-Bus StatusNotifierItem, no eframe), with its own single-instance
  lock and its own 2 s status poll. Open brings the window forward through the window's single-instance channel,
  or starts the window process; Open folder, Pause and Resume go to the agent; Quit stops the agent, then ends
  the window and itself.
- The window: a normal process that ends when it is closed (the agent keeps syncing). It starts the tray process
  if none runs, and its Quit ends the tray process too.

The single-instance channel takes a name (window or tray) and a command (`show` or `quit`). The Linux login entry
runs `--tray`, and an older entry's `--hidden` means the same. Windows and macOS keep hiding the window into the
tray, as before.

Tests: the window and the tray each hold one lock and can be told commands; the tray process's menu without a
window (fake agent, recorded outside); the Linux model (close ends the window, the tray's Quit ends it, the login
entry is kept); the Linux entry's golden file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The tray looked for an `org.kde.StatusNotifierWatcher` once, at start. At login waybar may come up a moment after
the app, which then had no tray (and removed its own login entry); a waybar restart lost the icon for good.

The tray process now serves its item whether or not a watcher is there, registers at once if one is, and watches
`NameOwnerChanged` for the watcher's name, registering again whenever one appears. An idle tray process waiting
for a watcher is fine. Its login entry is written on join and at each start whether or not a watcher is there now,
and removed only at sign-out (with the previous commit's split, the window no longer decides it from a tray).

Test (private dbus-daemon): the item starts before any watcher, registers once one appears, and registers again
after the watcher is gone and a new one appears. It fails with the watching turned off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
Drops mslnk, the one crate no other Craft app uses. The paths go to
PowerShell as environment variables, never as script text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
The reference sections move unchanged into docs/: install.md,
server.md, agent.md and development.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RC1oqfy9kZznj94RjMojyz
@itrycodinganditsbad
itrycodinganditsbad merged commit f94d379 into main Oct 19, 2026
4 checks passed
@itrycodinganditsbad
itrycodinganditsbad deleted the desktop-app branch October 21, 2026 00:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant