Files
pipelines/android
alan 9ca775291b Give the Android client a dark-first Material 3 look and TUI-style graph terminals
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.
2026-10-14 12:36:58 +01:00
..

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:

cd android
gradle wrapper --gradle-version 8.9

Until then, build with a locally installed Gradle:

cd android
gradle :app:assembleDebug

Build, test and install

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).