Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .github/workflows/desktop.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: Desktop

on:
pull_request:
paths:
- 'desktop/**'
- '.github/workflows/desktop.yml'
# The page's half of the shell bridge. The Python contract test holds the
# two sides together, but a change here should still build the window.
- 'ui-web/src/app/connection.ts'
- 'ui-web/src/state/look.ts'
- 'ui-web/src/state/shellWindow.ts'
- 'tests/test_desktop_shell_contract.py'

concurrency:
group: desktop-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
typecheck:
name: swift typecheck
runs-on: macos-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v7

# The app is a single top-level source file, so typechecking it is also
# checking that the window, the shell bridge and the WebKit delegates
# still compile together. It needs no simulator, signing identity or GUI.
- name: Typecheck the window
run: >-
/usr/bin/swiftc -typecheck
-target "$(uname -m)-apple-macosx12.0"
-framework Cocoa -framework WebKit desktop/macos/RavenDesktop.swift

- name: Typecheck the icon renderer
run: >-
/usr/bin/swiftc -typecheck
-target "$(uname -m)-apple-macosx12.0"
-framework Cocoa -framework WebKit desktop/macos/render_svg.swift

# The navigation matrix decides whether a click becomes a page or a file.
# Getting it wrong replaces the window with the file, which is exactly the
# bug this step exists to keep out.
- name: Check the navigation policy
run: |
/usr/bin/swiftc -O -framework Cocoa -framework WebKit \
-target "$(uname -m)-apple-macosx12.0" \
-o "$RUNNER_TEMP/raven-desktop" desktop/macos/RavenDesktop.swift
/usr/bin/vtool -show-build "$RUNNER_TEMP/raven-desktop" |
grep -F "minos 12.0"
RAVEN_DESKTOP_SELFTEST=1 "$RUNNER_TEMP/raven-desktop"
1 change: 1 addition & 0 deletions commitlint.config.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ const TOP_LEVEL_TREES = [
"agents",
"benchmarks",
"bridge",
"desktop",
"docs",
"evolver",
"plugins-dist",
Expand Down
4 changes: 4 additions & 0 deletions desktop/macos/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Swift module cache and build output. The cache stores absolute paths from
# the machine that compiled, so it must never be committed.
.modulecache/
build/
127 changes: 127 additions & 0 deletions desktop/macos/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Raven Desktop (macOS)

`~/Applications/Raven.app` is a small macOS window that shows the Raven web UI.
It exists because a browser tab is easy to lose among other tabs, and because
starting the gateway from a terminal every time gets old.

The app does not ship a second UI. On launch it runs `scripts/launch.sh`, which
asks the installed `raven` CLI for the one-time authenticated URL; the app loads
that URL into a `WKWebView`. The CLI is the only runtime dependency, and it owns
the whole gateway lifecycle: attaching to one that is already up, waiting for
one that is starting, and starting one when there is none.

```
Raven.app
+-- Contents/Resources/scripts/launch.sh starts/checks `raven web`
`-- /auth#<nonce>
`-- http://127.0.0.1:<port>/ the same page as `raven web`
```

## Build

```sh
cd desktop/macos
./build.sh
```

Needs macOS 12+, the Xcode Command Line Tools (`swiftc`, `sips`, `iconutil`)
and the `raven` CLI on `PATH` or at `~/.local/bin/raven`. The build compiles
the Swift source, renders `ui-web/src/assets/raven-mark.svg` into an `.icns`,
assembles the bundle and signs it ad hoc. Set `RAVEN_DESKTOP_APP` to build
somewhere other than `~/Applications/Raven.app`.

Build output goes into `desktop/macos/build/` and is ignored by git. Delete
`build/AppIcon.png` to force a re-render of the icon. On a Mac that has never
opened the app, Gatekeeper may require Right-click -> Open, or re-sign the
bundle with a Developer ID.

## What the launcher does

Finder launches apps with a short `PATH`, so the launcher adds `~/.local/bin`.
It resolves the `raven` CLI from `PATH` (falling back to
`~/.local/bin/raven`) and runs one command:

```sh
raven web --print-url
```

That command attaches to a running gateway, waits for one that is starting, or
starts a resident one, then prints the one-time `/auth#<nonce>` URL on stdout.
Progress and errors go to stderr. The launcher never stops a gateway: an empty
probe can mean "still booting", and stopping it there would kill the launch it
was trying to join.

The app marks itself as `RavenShell` in the user agent and implements the
frontend's small message bridge: the page lifts the native splash with `ready`,
asks for a fresh sign-in link with `reauth` after a gateway restart, and reports
`theme`, `drag` and `zoom` for the hidden title bar. If WebKit's content process
dies, the app reconnects. Cmd-Shift-R reconnects manually. Links that leave
localhost go to the system browser. Closing the window quits the app but leaves
the gateway running.

## Layout

The window and its build scripts live under `desktop/macos/`. The branch also
carries three small changes outside that tree because the window needs them: a
`--print-url` mode in `raven/cli/serve_commands.py` so the launcher can ask for
one URL instead of probing the gateway itself, `desktop` in the commit-scope
list, and the CI job plus contract test that keep the bridge honest. Everything
else upstream is untouched.

| File | What it does |
| --- | --- |
| `RavenDesktop.swift` | Window, menus, WKWebView, the `raven` message bridge and auth handling |
| `scripts/launch.sh` | Prints the auth URL through `raven web --print-url` |
| `build.sh` | Compiles, builds the icon, assembles and signs the bundle |
| `render_svg.swift` | Offscreen SVG to PNG, for cases where `qlmanage` is unavailable |

## Verification

The shell parts can be checked without the app:

```sh
cd desktop/macos
RAVEN_DESKTOP_APP=/tmp/Raven.app ./build.sh
/tmp/Raven.app/Contents/Resources/scripts/launch.sh # prints an http://127.0.0.1:<port>/auth#... URL
open /tmp/Raven.app
```

The native window itself needs a Mac with a GUI, so it is not covered by CI.
The launcher's argument contract has a pytest (`tests/test_desktop_macos_launcher.py`)
that runs on every platform with a POSIX shell, and a macOS CI job typechecks
the Swift sources whenever `desktop/**` changes. That job also runs the
navigation matrix (`RAVEN_DESKTOP_SELFTEST=1`), which checks what a click does
without opening a window or contacting a gateway.

## Files, downloads and new windows

The page hands a delivered file to an `<a download>` link. A `WKWebView` treats
that as a navigation unless the app says otherwise, so a click would replace the
window with the file itself and take the page's script context with it. The app
answers `shouldPerformDownload` with a `WKDownload` instead, and saves to the
reader's `Downloads` folder, adding ` (2)` rather than overwriting a file that is
already there. The same check runs at response time for anything the gateway
marks `Content-Disposition: attachment` or that WebKit cannot display.

A link that asks for a new window (`target=_blank`, `window.open`) gets a real
child window next to the main one, so "open in a new tab" no longer navigates
Raven away from itself. External links still go to the system browser.

`File -> Back` (Cmd-[) and `File -> Forward` (Cmd-]) exist because the window has
no browser toolbar; they return to the page from anywhere it can navigate to.

## Known limits

Only macOS. The app is ad hoc signed, not notarized, so Gatekeeper may require
Right-click -> Open on a machine that has never seen it. It assumes the gateway
serves an `/auth#<nonce>` URL as `raven web --print-url` does today; if that
contract changes, the launcher and the CLI flag need to change together.

The app itself stores no credentials, but WebKit keeps the gateway's HttpOnly
session cookie in its default data store, so the window stays signed in across
launches just as a browser tab does.

Finder launches an app with the login environment, not a shell profile. Provider
keys, proxy settings or a custom `RAVEN_HOME` exported from `.zshrc` do not
reach a gateway started this way; start the app from a terminal when those are
needed, or put the settings somewhere Raven reads at startup.
Loading
Loading