# ori-desktop — a Wails desktop shell for ori

`ori-desktop` wraps the [ori](../README.md) web client in a native window built with
[Wails v2](https://wails.io) (Go + the platform's webview). It does **not** reimplement ori:
the ori server keeps serving the React SPA and the `/ws`, `/api/files`, `/ws/terminal`
endpoints. The desktop app only

1. shows a small **connection screen** with the ori server URL (default `http://localhost:8888`),
   remembered between runs in a JSON settings file;
2. checks the server with **`GET /healthz`** through a Go-bound method;
3. then displays the **ori webapp itself** inside the window.

It is a separate Go module (`rickub.com/bots-garden/ori-desktop`), so the parent
repository's `go test ./...` and `make build` are unaffected.

## Prerequisites

- Go 1.25+ (the module follows Wails v2.16's requirement).
- The Wails v2 CLI: `go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0`
  (then make sure `$(go env GOPATH)/bin` is on your `PATH`).
- The platform GUI toolchain Wails needs — run `wails doctor` to see what is missing:
  - **Linux**: `gcc`, `pkg-config`, `libgtk-3-dev`, `libwebkit2gtk-4.0-dev` (or `-4.1-dev`
    with `-tags webkit2_41`);
  - **macOS**: Xcode command line tools;
  - **Windows**: WebView2 runtime (preinstalled on Windows 10/11); NSIS only for the installer.
- A running ori server. From the repository root: `make run` or `make run-mock`.

No Node/npm is needed: the frontend is plain HTML/CSS/JS embedded as-is (no bundler).

## Run in development mode

```bash
cd ori-desktop
wails dev
```

`wails dev` builds the Go side, opens the window, and reloads the frontend when a file under
`frontend/src/` changes (`assetdir` in `wails.json`). It also serves the app at
http://localhost:34115 so you can open it in a normal browser with devtools and still call the
Go methods.

## Build a redistributable binary

```bash
cd ori-desktop
wails build            # → build/bin/ori-desktop (or .app / .exe)
# or, from the repository root:
make desktop
```

Cross-compiling for Windows from Linux/macOS works without any C toolchain:
`wails build -platform windows/amd64` → `build/bin/ori-desktop.exe`.

## Tests

The connection logic is pure Go and tested without any GUI dependency:

```bash
cd ori-desktop && go test ./internal/...
# or, from the repository root:
make desktop-test
```

`internal/settings` covers load/save round trips, defaults on a first run, invalid files and URL
normalisation; `internal/health` covers `/healthz` against an `httptest` server (healthy,
non-ori, unreachable, cancelled).

## How it connects to ori

```
┌──────────────── ori-desktop (Wails window) ─────────────────┐
│ frontend/src (embedded, wails:// origin)                    │
│   connection screen ──► window.go.main.App.Connect(url)     │
│                             │ Go: NormalizeURL → GET /healthz → Save settings
│                             ▼                               │
│   <iframe src="http://localhost:8888/">  ◄── ori server serves the SPA,
│        SPA opens ws://localhost:8888/ws, /ws/terminal, /api/files as usual
└─────────────────────────────────────────────────────────────┘
```

**Why an iframe?** Wails v2 gives no runtime call to navigate the main webview to an external
URL; the window always shows the embedded frontend (`runtime.BrowserOpenURL` opens the system
browser instead, which is offered as the "Open in browser" fallback). Loading ori in an
`<iframe>` keeps a thin native bar (URL, Reload, Open in browser, Disconnect) around the
untouched ori SPA. This works because ori sends no `X-Frame-Options`/CSP `frame-ancestors`
header, and because the SPA derives its WebSocket URLs from `window.location` — inside the
iframe that is the ori origin itself, so ori's `localhost:*` WebSocket origin check passes.

On macOS, `build/darwin/Info.plist` sets `NSAppTransportSecurity/NSAllowsLocalNetworking` so
App Transport Security allows the plain-HTTP loopback load.

### Go methods bound to the frontend (`app.go`)

| Method | Purpose |
| --- | --- |
| `GetConfig() → settings.Settings` | Remembered settings (defaults on a first run). |
| `SaveConfig(settings.Settings)` | Normalise the URL and persist. |
| `CheckHealth(url) → health.Report` | `GET <url>/healthz`; never rejects — `ok`, `statusCode`, `detail`. |
| `Connect(url) → string` | Normalise, check health, remember the URL, return the base URL to load. |
| `OpenInBrowser(url)` | `runtime.BrowserOpenURL` fallback. |
| `SettingsPath() → string` | Where the settings file lives (displayed on the screen). |

The frontend calls them as `window.go.main.App.<Method>()` (Promises). The typed wrappers that
`wails dev`/`wails build` generate under `frontend/wailsjs/` are gitignored because nothing
imports them; regenerate them with `wails generate module` if you want the `.d.ts` files.

### Settings file

`<user config dir>/ori-desktop/settings.json`, i.e. `~/.config/ori-desktop/settings.json` on
Linux, `~/Library/Application Support/ori-desktop/settings.json` on macOS,
`%AppData%\ori-desktop\settings.json` on Windows:

```json
{
  "serverUrl": "http://localhost:8888"
}
```

## Layout

```
ori-desktop/
├── main.go              Wails bootstrap (window options, embedded assets, bindings)
├── app.go               Go methods bound to the frontend
├── wails.json           Wails project configuration
├── internal/settings/   settings file (load/save/normalise) + tests
├── internal/health/     GET /healthz probe + tests
├── frontend/src/        index.html, main.css, main.js (embedded ES module, no bundler)
└── build/               Wails build assets (icon, Info.plist, Windows manifest); build/bin is the output
```

## Status / known limitations

- Verified so far: unit tests, `go vet`, and a Windows cross-build (`wails build -platform
  windows/amd64`) from a Linux sandbox without GUI libraries. The window itself has not yet been
  launched (no WebKitGTK in that sandbox) — see the repository's `.memory/` notes.
- ori is loaded over plain HTTP; use it against local or trusted servers only.
- Ori's `--addr` other than `:8888` simply means typing the matching URL on the connection screen.