Skip to content

Latest commit

 

History

History
205 lines (173 loc) · 11 KB

macos-app.md

File metadata and controls

205 lines (173 loc) · 11 KB

Running as a macOS app

Instead of living in a browser tab, soloops also runs as a standalone app with a dock icon, a menu bar and a tray item — a Tauri window onto the same interface, around 10 MB, using the macOS WebView rather than shipping its own Chromium.

npm run app          # start the app in development mode
npm run app:build    # build soloops.app and a DMG

The result lands in apps/desktop/src-tauri/target/release/bundle/macos/soloops.app — drag it to /Applications once and you're done.

What the app adds on top of the web UI:

  • Starting the containers itself. On launch it checks whether web and API respond. If they don't, it starts Docker Desktop and runs docker compose up -d; the splash screen reports what it is waiting for. Closing the window leaves the containers running so the worker keeps syncing calendars and mail — quit them from the tray menu.

  • Keyboard shortcuts. ⌘1 to ⌘9 jump to the modules, ⌘R reloads, ⌘⇧M fetches the inbox, ⌘⇧P opens the port overview, ⌘⇧Z shows the time widget.

  • Port overview (⌘⇧P or tray). The same thing as npm run ports, in a window: which service listens on which port, where it comes from, and a button to stop it. The app shells out to scripts/ports.sh for this — the logic exists in exactly one place.

  • Time widget (⌘⇧Z or tray). A frameless pill on top of everything: a dot that says whether the clock runs, the project key, the elapsed time. The whole pill is handle and switch at once — drag it and it moves, click it and it folds out; what tells the two apart is whether the pointer travelled more than four pixels. Letting go snaps it to the nearest of eight resting places — the four corners and the middle of the four edges — so it lands out of the way instead of in the middle of what is being read. Where it sat, whether it was unfolded and whether it was on at all survive a restart in data/tracker.json.

    It also stays on the screen it was dropped on. That needs saying, because the obvious implementation gets it wrong: tao reports a monitor's position as its bounds times that monitor's backing scale, and a window's position times the scale of the screen the window is on. Put a 2× laptop display next to a 1× monitor and those two numbers are no longer in the same coordinate system — so the geometry in tracker.rs is done entirely in points, the screen a widget belongs to is the one containing its centre, and the name of that screen is remembered in data/tracker.json. A monitor that has been unplugged is simply gone, and then the first screen takes over.

    It stays where it is put: it joins every space rather than waiting on the one it was opened on, and a thread brings it back whenever macOS has hidden it along with the rest of the app (⌘H, "Hide Others"). That thread keeps its hands off while the widget is being dragged — macOS reports a window crossing a screen boundary as hidden for a moment, and answering that by snapping it back to its anchor every three seconds is what a flickering widget looks like. The one thing that still covers it is another app's fullscreen window. Switching it off is a decision and stays one — the button for that sits inside the unfolded panel, not next to the fold arrow where a misclick used to make it look crashed.

    Unfolded it lists the active projects by client with the hours that are not on an invoice yet; one click starts the clock. While it runs it shows the commits that have landed in the window so far — the ones that will become the service description on the invoice, see Modules. Stopping is one button; the commits are filled in a few minutes later, because the push comes after the clock.

    The widget talks to the API through Rust and never sees the SERVICE_TOKEN. Its commands hang off that one window (capabilities/tracker.json): read the timer, start it, stop it, read the project list, read the commits of an entry, fold, snap, disappear. Nothing else, and no other window.

  • Backup into iCloud (Ansicht → Backup & iCloud … or tray). One archive per run holding a pg_dump of the database and a copy of data/, written into a folder that syncs itself — iCloud Drive by default (~/Library/Mobile Documents/com~apple~CloudDocs/soloops-backup), any other folder if one is chosen. Off until a folder is confirmed; once on, every 24 hours by default, keeping the newest 14 archives.

    The database itself stays local, deliberately. Pointing Postgres at a synced folder loses it: iCloud writes when it feels like it, evicts files it believes are cold, and resolves a conflict by keeping both versions side by side. The failure does not show up on the day it is caused — it shows up weeks later as a cluster that will not start. Snapshots into that folder cannot corrupt what they copy.

    The archive is built under .<name>.part and renamed into place at the very end, because iCloud starts uploading the moment a file appears. A dump of under a kilobyte is treated as a failed run and thrown away — otherwise a stack that was not running would rotate away fourteen good snapshots over fourteen days. A failed run leaves the timestamp where it was, so the next tick tries again instead of waiting out the interval.

    Onto a new Mac: clone the repository, copy the .env, npm run up, then open this window and restore the newest archive. Restoring overwrites what is there — the button arms on the first click and does it on the second, like the port window's. Files go back first and the database last, and afterwards the interface needs a reload (⌘R). Settings and status live in data/backup.json; the window's commands hang off that one window (capabilities/backup.json), and pg_dump, tar and psql run in Rust — the page knows neither the .env nor the database.

  • Activity recording. One sample every 20 seconds: which app is in front, what its window is called, how long nobody has typed. Off by default — the checkbox sits in the tray and under Ansicht and takes effect immediately. On first run macOS asks for Accessibility permission (System Settings > Privacy & Security); without it, nothing is recorded. Details under Activity.

  • Follow-up reminders. A lead whose follow-up falls due becomes a macOS notification — once per date, and only between 8 and 22. Details under Follow-ups.

  • Connecting Claude. Einstellungen → Claude writes the MCP connector into Claude Desktop and Claude Code with one click. Only the app can do this: the API runs in a container and has no home directory to write into. Details under MCP server.

  • Tray menu. Show window, fetch inbox, ports, backup, time widget on/off, activity on/off, stop containers, quit.

A menu item is handled once, by the handler on the builder. Tauri keeps one list of menu listeners for the whole app and calls every one of them for every event, wherever the menu sits, so a second handler on the tray icon would run each click twice — which for the two check marks is the difference between switching and not switching.

Installing it

Tag a version and .github/workflows/release.yml builds the .dmg and attaches it to the release — git tag v0.1.1 && git push --tags, or run the workflow by hand with a tag as input.

The build is ad-hoc signed: there is no Developer-ID certificate in CI, so macOS asks once. Right-click → Open on first launch, or take the download's quarantine mark off with xattr -d com.apple.quarantine /Applications/soloops.app. The release notes say so too, because that is where somebody reads it.

The install window

A DMG opens as a Finder window, and by default that window is two icons on grey with nothing explaining what to do with them. This one is drawn: the word mark with its acid dot, an arrow from the app to the Applications folder, what to do, and the sentence about the first launch — in raised, the palette's colour for what lies on top of the work surface, which is also the closest the palette gets to the white the app icon carries.

The picture is generated, not hand-drawn:

python3 apps/desktop/src-tauri/icons/dmg-background.py

It writes icons/dmg-background.png at twice the size with 144 dpi, so the Finder lays it out at 660×400 points with a Retina display's pixels. The icon positions in that script and the ones in tauri.conf.json have to agree — the arrow is drawn into the gap between them.

One thing it cannot fix: icons/icon.icns has an opaque white background rather than the transparent rounded square macOS expects, so the icon shows as a white tile — in this window, and in the Dock and Launchpad too. The window's colour was chosen to make that as quiet as possible.

How it finds the repository

The app is the frame around a stack that lives in a directory — the compose file, the .env, data/. That path used to be baked in at build time, which works for the machine that compiled it and for no other: an app built on a CI runner would point at /Users/runner/work/…, and on the Mac that downloads it nothing is behind that path.

So it looks, in this order (see src/project.rs):

  1. SOLOOPS_DIR from the environment — if somebody says so, that wins
  2. the path remembered from a previous answer, under ~/Library/Application Support/com.philippniestroj.soloops/dir
  3. the path baked in at build time, but only if it exists — the development build stays as convenient as it was
  4. ~/Desktop/PNSE/soloops, ~/soloops, ~/Developer/soloops, ~/Projects/soloops
  5. otherwise it asks once, with a folder dialog, and remembers the answer

A directory counts as the repository when it holds both a docker-compose.yml and a package.json whose name is soloops. One mark alone is any project with containers, or any npm project.

Building locally requires the Rust toolchain (rustup) and the Xcode command line tools.

The loaded interface gets as good as no access to Tauri APIs (see capabilities/default.json): it is the same web app as in the browser, just in a different frame. Menu, tray and container startup run entirely in Rust.

The single exception is the Claude connection (capabilities/claude.json): there the interface may call exactly three commands — read the status, write the connector, restart Claude Desktop. The commands are listed in build.rs, because Tauri treats a page under http://localhost as a remote origin and allows nothing there that no capability names. Anything beyond those three stays with the menu and Rust.