Files
pipelines/android/README.md
T
alan cee9fb2f79 Fix graph fitting, pan bounds, auto-connect and run wording in the Android client
An emulator run against the live server exposed four usability defects and one
legibility defect, all fixed here:

- The workflow graph was not fit-to-content: 3- and 4-stage graphs showed only the
  first columns until the user panned. The initial view now fits and centres the
  whole graph, scaling down when it is wider than the viewport.
- A panned graph could be dragged completely out of view with no way back. Pan is
  now clamped so content stays visible, and a 'Fit graph to view' action restores
  the fitted view.
- The app did not connect on launch even with a saved server URL. It now connects
  from the saved URL using the existing bounded backoff; an explicit Disconnect
  still stays authoritative for the session.
- The runs list said 'N steps' while run detail said 'N recorded visits'. Both now
  use the server's own vocabulary ('N completed visits' / 'N recorded visits')
  through one shared helper in Format.kt.
- Outcome labels: labels are drawn after all curves so none is crossed, dimmed
  labels use onSurfaceVariant, and executed labels no longer resolve to
  near-invisible container accents ('rejected' measured ~1.2:1 before).

Verified: :app:compileDebugKotlin, :app:assembleDebug and :app:testDebugUnitTest
succeed offline with 28 tests and 0 failures (WorkflowGraphTest grew to 9 tests
covering fitScale, clampOffset extremes and label slots), and the app was driven
on the Pixel_Fold_API_36 emulator against the live server with before/after
screenshots and no FATAL or Compose exception in logcat.
2026-10-13 21:55:16 +01:00

142 lines
6.6 KiB
Markdown

# Pipelines Android client
A native Android (Kotlin + Jetpack Compose Material 3) client for an existing
Pipelines server. All execution, model credentials, definitions and run history
stay on the server; the app only speaks the existing WebSocket protocol.
## Scope and safety
- **Trusted LAN/VPN only.** The Pipelines API has **no authentication** and is
**not internet-safe**. Do not expose the server to untrusted networks.
- **No secrets.** The app stores no credentials, tokens or provider keys and
sends no auth headers. Only the server URL and workspace path are persisted as
plain, non-secret preferences.
- **No hardcoded server.** The server URL and workspace path must be entered
explicitly by the user; there is no default/disposable address baked in.
- The app does **not** run Docker, execute stages, or reimplement any Go
parsing/execution logic. `android/` contains only the client.
## Requirements
- JDK 17 (see `compileOptions` / `kotlinOptions.jvmTarget`).
- Android SDK with a platform and build-tools matching `compileSdk = 35`
(`app/build.gradle.kts`), and `ANDROID_HOME`/`ANDROID_SDK_ROOT` set.
- Gradle 8.9+ (AGP 8.7.2, Kotlin 2.0.21).
The version numbers above are deliberate defaults chosen without a discovered
SDK; adjust `compileSdk`, `targetSdk`, and the versions in
`gradle/libs.versions.toml` to whatever is actually installed. If a required
SDK/Gradle component is missing, fix the environment rather than downloading
untracked artifacts.
### Gradle wrapper
`gradle/wrapper/gradle-wrapper.jar` is a generated binary and is intentionally
**not committed**. Generate a working wrapper on a machine with Gradle installed:
```sh
cd android
gradle wrapper --gradle-version 8.9
```
Until then, build with a locally installed Gradle:
```sh
cd android
gradle :app:assembleDebug
```
## Build, test and install
```sh
cd android
gradle :app:testDebugUnitTest # protocol/URL/graph unit tests
gradle :app:assembleDebug # debug APK
gradle :app:lintDebug # Android lint
# install on a connected device/emulator:
gradle :app:installDebug
adb shell am start -n net.awan.pipelines/.MainActivity
```
## Configuration
Open the **Settings** tab and enter:
- **Server URL** — `ws://HOST:PORT/connect` (LAN/VPN) or `wss://…/connect`
(proxy/VPN). A path is optional and defaults to `/connect`, matching the Go
server's `GET /connect`. `http(s)`, userinfo and fragments are rejected with a
specific message.
- **Workspace path** — an **absolute directory that already exists on the
execution server**. This is *not* the phone's storage. For Docker, mount the
host directory at the same absolute path with the owner's UID/GID so the
server can resolve it (see `docs/docker.md` and `compose.yaml`). The field
flags a non-absolute path and will not save it, mirroring the repository's
start-run guard.
Tap **Connect** to open the single shared WebSocket (probed with `ping`, showing
the server build). Reconnect uses bounded exponential backoff; **Disconnect**
stops it.
## Features
- Pipeline list (search/refresh, empty/error/loading states), pipeline details
(version list, content hash, source) and the workflow graph.
- Workflow graph composable: content-sized nodes, labelled outcome edges
(`error*` marks the implicit fallback), `#success`/`#failure` terminals, loops
and branches, pan/zoom, and run highlighting (executed routes highlighted,
others dimmed) plus a screen-reader description.
- Run history with server `usage` aggregates, and run details with steps
(status/outcome/diagnostic/session/transcript/file changes/notifications/
control evidence). Session evidence is scoped to the selected run and each
record is rendered (sequence/session id/backend/directory/data/diagnostic) on
demand via `get_run_evidence`; it is never part of the 1s poll.
- A shared connection banner above every screen surfaces a distinct
Idle/Connecting/Disconnected state with a Reconnect action (and stays hidden
while connected), so a dropped connection is not just a generic request error.
- Start run (confirmation dialog; sends `PipelineID`, `Version`, a reused
`request_key` ≤128 chars, the configured absolute workspace and `input.prompt`)
and cancel run (confirmation; sends the `RunID`, then refreshes). Retry is
offered only for terminal failed runs.
- A run being polled at a fixed 1s interval is stopped as soon as it is no
longer executing.
## Architecture
```
data/protocol kotlinx.serialization models mirroring internal/protocol/*
(Message, Graph/Stage, RunDetail/RunStep, UsageStats, …) plus
GraphSemantics reproducing internal/tui/graph.go rules.
data/transport ServerUrl validation (mirrors internal/client/config.go) and
PipelinesClient — one reused WebSocket, serialized requests,
client ids matched against replies, unsolicited envelopes
dropped, bounded reconnect backoff.
data SettingsRepository (non-secret prefs) and PipelinesRepository
(typed request builders + per-session graph/detail cache).
ui Compose Material 3 screens, one AppViewModel, navigation.
```
## Verification status
Verified on macOS with the host toolchain (JDK 17 from Android Studio,
`ANDROID_HOME=/Users/alan/Library/Android/sdk`, Gradle 8.11.1 `--offline`):
- `:app:compileDebugKotlin`, `:app:assembleDebug` and `:app:testDebugUnitTest`
all succeed; **20 unit tests, 0 failures** (protocol model, graph semantics,
server URL, workflow-graph layout). Re-run with `--rerun-tasks` to confirm.
- The debug APK was installed and driven on the `Pixel_Fold_API_36` emulator
(Android 16) against a live server at `ws://10.0.2.2:8080/connect` with
workspace `/Users/alan`. Settings, pipeline list (all 9 pipelines), pipeline
detail, the workflow graph, run history, run detail and the disconnected/
reconnect states were captured to `captures/` (git-ignored) and reviewed.
- `adb logcat` for the app package contained no `FATAL EXCEPTION`, Compose or
other runtime exception during the sweep.
Known limitations of that run: pinch-zoom could not be driven through `adb`
(single-touch pan only) and one portrait Fold viewport was used. A follow-up pass
fitted the graph to its viewport on first layout, clamped panning so the content
cannot leave the view, added a "Fit graph to view" action, connected on launch
when a server URL is already saved, and made the completed/recorded visit wording
and the outcome-label contrast consistent. The fitted graph still sits slightly
above the box's vertical centre, because the layout box includes padding that is
not drawn.