9ca775291b
Three UI changes requested after reviewing the first on-device screenshots:
- Dark-first theme: the app now owns its colour scheme instead of following the
system wallpaper. Theme.kt defaults to a deliberate darkColorScheme built from
a mint/teal seed with an amber tertiary (new Color.kt) so it matches the dark
Pipelines TUI; dynamic colour is gone and a complete light scheme is retained
for when it is explicitly requested. themes.xml/colors.xml give the app a dark
window background and dark system bars with light icons, so launching never
flashes light.
- Workflow graph matches the TUI: the #success/#failure terminals now share a
lower row under the stage row, with arrows entering their top borders and the
error -> #failure route leaving the bottom of its source stage, mirroring
internal/tui/graph_layout.go ('Terminals share a lower row...') and graph.go's
'[FAILURE] [SUCCESS]' bottom row. Fit-to-content, pan clamping, the Fit
action, run highlighting and the TalkBack description are preserved.
- More style: consistent Material 3 top app bars for Pipelines, Runs and
Settings, the new colour scheme applied across the screens and state
components, and monospace retained for hashes, source and run input/output.
Verified on the host and on the device: :app:compileDebugKotlin, :app:assembleDebug
and :app:testDebugUnitTest succeed offline with 34 tests and 0 failures
(WorkflowGraphTest grew to 15 tests covering the terminal row, bottom exits and
fit/clamp), and the app was run on the Pixel_Fold_API_36 emulator in dark mode
against the live server: the whole 4-stage graph renders with its terminal row,
and the list, detail and settings screens use the new theme.
156 lines
7.6 KiB
Markdown
156 lines
7.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 stage nodes laid out in one row in
|
|
declaration order, with `#failure`/`#success` terminals sharing a lower row and
|
|
arrows entering their top borders (an `error -> #failure` route leaves its
|
|
source's bottom); labelled outcome edges (`error*` marks the implicit
|
|
fallback), loops and branches, pan/zoom, and run highlighting (executed routes
|
|
highlighted, others dimmed) plus a screen-reader description.
|
|
- Dark-first Material 3 theme with an app-owned colour scheme (no dynamic/
|
|
wallpaper colour): the dark scheme is the default and the window background and
|
|
system bars are dark so launching shows no light flash; a complete light scheme
|
|
is retained for when it is explicitly requested.
|
|
- Consistent Material 3 top app bars on Pipelines, Runs and Settings (and the
|
|
existing back/refresh/start/cancel/retry bars on the detail screens).
|
|
- 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; **34 unit tests, 0 failures** (protocol model, graph semantics,
|
|
server URL, workflow-graph layout including the terminal row, bottom exits and
|
|
back edges). Re-run with `--rerun-tasks` to confirm.
|
|
- The debug APK was installed and driven on the `Pixel_Fold_API_36` emulator
|
|
(Android 16, `adb shell cmd uimode night yes`) against a live server at
|
|
`ws://10.0.2.2:8080/connect` with workspace `/Users/alan/repos/pipelines`.
|
|
Settings, pipeline list (all 9 pipelines), pipeline detail, the workflow graph,
|
|
run history and run detail were captured to `captures/` and
|
|
`captures/style_pass/` (both 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. A later style pass made the theme dark-first (app-owned scheme; the
|
|
launch window/bar colours match it) and moved the `#failure`/`#success` terminals
|
|
to a lower row beneath the stage row; before/after captures for the theme, graph
|
|
and app bar/style are under `captures/style_pass/` (`*_before.png` are the
|
|
pre-change baseline referenced by the task, `*_after.png` are the new build).
|