1828171a9c
- Pipeline detail and run detail are now tabbed: run detail has Summary, Graph, Input, Output, Evidence and Steps, pipeline detail has Summary, Graph and Source, with the version list in Summary. The graph gets a tab of its own, so it uses the whole content area with its Fit and expand controls. Selection is remembered and the tabs carry real tab semantics. - The code-like blocks (Input, Output, Source, prompt, transcripts) are styled content cards with a label header, monospace body, a copy action and a bounded height that scrolls internally, instead of a raw bordered div. - Content inside a tab breaks down into collapsible inner sections (DetailTabs.kt, CodeBlock.kt), reusing the existing section component with remembered state. - Foldable layout is driven by window width (WindowSize.kt): narrow windows keep the single-pane tabs, wide windows use list-and-detail side by side with the detail capped to a readable width. Verified: :app:assembleDebug and :app:testDebugUnitTest succeed offline with 60 tests and 0 failures (new WindowSizeTest and DetailTabsTest), and the reviewer drove every tab plus both a narrow and a wide window on the emulator (captures in android/captures/tabs_pass/view/). The implementer's own capture set in that directory is unusable: it wrote screencap's multi-display warning into the files (they begin with ASCII '[Warning', not the PNG magic), so only the reviewer's captures were reviewed.
300 lines
18 KiB
Markdown
300 lines
18 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. Edges are drawn as
|
|
axis-aligned orthogonal polylines like the TUI (`routePoints` computes the
|
|
path once per layout and stores it on `EdgeLayout.points`), and each arrowhead
|
|
points along its route's final segment rather than the from-to chord. Pinch
|
|
zoom is anchored to the gesture centroid: the pure `zoomAbout` keeps the
|
|
content point under the fingers fixed (clamped to `MIN_SCALE`/`MAX_SCALE`) and
|
|
the existing pan clamp is applied afterwards, so the content no longer slides
|
|
away from the fingers.
|
|
- One shared graph-panel height (`collapsedGraphHeight`/`expandedGraphHeight`)
|
|
replaces the former 360.dp and 340.dp literals, so both detail screens render
|
|
the graph at the same size: about 58% of the window height floored at a height
|
|
that still fits a 4-stage graph with its terminal row. The graph's TopEnd
|
|
control cluster pairs "Fit graph to view" with an expand/collapse toggle that
|
|
grows the panel to about the full window height; the expanded state is stored
|
|
in `rememberSaveable` and the panel refits on resize. Because the panel lives
|
|
inside each screen's `verticalScroll` column, growing it only extends it below
|
|
the fold, so expanding also requests `BringIntoViewRequester` to scroll the
|
|
taller panel back into the visible viewport instead of leaving the graph
|
|
centred off-screen.
|
|
- 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).
|
|
- Both detail screens are tabbed via one shared `ui/components/DetailTabs.kt`:
|
|
run detail exposes Summary, Graph, Input, Output, Evidence and Steps, pipeline
|
|
detail Summary, Graph and Source, with Summary first and the default. The run's
|
|
six tabs scroll horizontally on a narrow window; on a wide window the same tabs
|
|
render as a vertical selectable rail. Selection is `rememberSaveable` (survives
|
|
recomposition and configuration changes) and the tabs carry real tab semantics
|
|
(`Role.Tab` + selected state), so selection is never conveyed by colour alone.
|
|
Only the selected tab's body composes (`when`), each tab is a single
|
|
`LazyColumn`, and the Graph tab keeps the full-height `WorkflowGraph` panel
|
|
with its Fit and expand controls.
|
|
- The Summary tab carries what each page header carried: for a run the
|
|
status/outcome/executing chip row, recorded + completed visits, pipeline
|
|
id/version, stage, workspace, content hash, start/finish/duration and the
|
|
failure diagnostic; for a pipeline the name, id/version, stages, content hash,
|
|
created/updated, latest version/version-created and the version list.
|
|
- Code-like content (Input, Output, Source, session transcripts, per-field and
|
|
evidence data, diagnostics) renders through one themed `ui/components/
|
|
CodeBlock.kt` card: `surfaceContainer` role, default rounded shape, a small
|
|
label header, a whole-block copy action (`LocalClipboardManager`) and monospace
|
|
at the shared size/line height, with a bounded height that scrolls internally
|
|
instead of pushing the page. Blank content renders nothing, and no raw bordered
|
|
monospace box remains.
|
|
- Inside each tab the existing `LazyListScope.collapsibleSection` (`SectionHeader`)
|
|
provides inner sections where content naturally breaks down: Output per result
|
|
field, Input per labelled part, Steps per stage group and Evidence per entry.
|
|
Each defaults to expanded and its collapsed set is `rememberSaveable`, so it
|
|
survives configuration changes; the sections are items of the tab's single
|
|
`LazyColumn`, so no scrollable nests inside a same-direction scrollable.
|
|
- Foldable-responsive layout driven by window size (`ui/WindowSize.kt`,
|
|
`isWideLayout(widthDp)` at a 600dp breakpoint, read from
|
|
`LocalConfiguration.current.screenWidthDp`): a narrow window keeps the
|
|
single-pane lists, top tabs and bottom navigation, while a wide window shows
|
|
the pipeline list beside the selected pipeline's tabs and the run list beside
|
|
the selected run's tabs (master pane ~360dp), with the detail tabs as a side
|
|
rail, the text column capped at a comfortable width and the graph using the
|
|
extra width. No material3-adaptive dependency is added.
|
|
- Both detail screens' sections are still collapsible via the shared
|
|
`SectionHeader`: tapping a header toggles it, an animated chevron rotates with
|
|
the state, the header sticks to the top of the list while its content scrolls
|
|
under an opaque background, and the state is exposed to accessibility
|
|
(`"Steps, expanded"`). Expanded state is `rememberSaveable`, per section and
|
|
per screen, defaulting to expanded. Real lists (versions, steps, session
|
|
evidence) are items of the one outer list, so nothing nests a scrollable.
|
|
- Steps render as a timeline in run detail: a leading status glyph connected to
|
|
the next step by an outcome-coloured line, the stage with its sequence/visit
|
|
number, an outcome chip and the duration, with every retained piece of evidence
|
|
(input, output, transcript, file changes, notifications, control evidence)
|
|
behind a collapsible, collapsed-by-default detail in monospace.
|
|
- The runs list is grouped by day (`Today`/`Yesterday`/date, newest first) under
|
|
sticky headers, with the usage aggregates as a metrics block (total, average
|
|
via `formatDuration`, and colour-coded succeeded/failed/canceled/interrupted/
|
|
active counts). Each card shows the pipeline name with a version chip, a
|
|
colour-coded status chip with a distinct icon per state
|
|
(running/queued/succeeded/failed/canceled/interrupted/active/unknown), a meta
|
|
row (run id, start time, duration) and the diagnostic only when non-blank,
|
|
clamped to two lines. The raw `resultPreview` is no longer printed, and
|
|
progress is shown honestly (completed visits + current stage, with an
|
|
indeterminate indicator while executing; no invented total).
|
|
- One centralised type scale (`ui/theme/Typography.kt`, passed to
|
|
`MaterialTheme` and exposed as named roles) defines the screen/app-bar title,
|
|
section header, card title, subtitle/meta, body and monospace data, applied on
|
|
the list and both 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; **53 unit tests, 0 failures** (protocol model, graph semantics,
|
|
server URL, workflow-graph layout including the terminal row, bottom exits,
|
|
back edges, orthogonal routing/axis alignment, arrowhead direction, the
|
|
shared panel height and the new `zoomAbout` anchor/clamp cases, plus duration
|
|
formatting, run-state mapping and run day-grouping). 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.
|
|
- The orthogonal-edge / resizable-panel pass was verified the same way: a
|
|
baseline APK was built from the pre-change tree and installed, then the new
|
|
build was installed and driven to the 4-stage pipeline-detail graph and a
|
|
run-detail graph with the executed route highlighted. `captures/graph_pass/`
|
|
(git-ignored) holds `pipeline_detail_before/after` and `run_detail_before/after`
|
|
pairs plus a panned state and the expanded panel after tapping the toggle
|
|
(`pipeline_detail_expanded_after`, `run_detail_panned_after`,
|
|
`run_detail_expanded_after`). A review of that pass found the expanded panel
|
|
scrolled below the fold (blank) and the PNGs prefixed by an adb stderr warning,
|
|
so the expand now scrolls the panel into view and the after-captures were
|
|
re-taken with a display id (`adb exec-out screencap -p -d <display-id>`) so no
|
|
warning leaks into the files. `adb logcat` showed no `FATAL EXCEPTION` and no
|
|
app/Compose 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).
|
|
|
|
The Runs-area pass (centroid zoom, collapsible sticky sections, runs list, steps
|
|
timeline, type hierarchy) was verified the same way on the `Pixel_Fold_API_36`
|
|
emulator (dark mode, `adb shell cmd uimode night yes`) against the live server:
|
|
the debug APK was installed, the list/detail/step flows were driven with
|
|
`adb shell input` and `uiautomator dump`, and captures were written to
|
|
`captures/runs_pass/` (git-ignored): `runs_list_top`,
|
|
`runs_list_scrolled_sticky` (a `13 Oct 2026` header pinned under the app bar),
|
|
`runs_list_states`, `runs_card_interrupted`, `run_detail_top`,
|
|
`run_detail_graph_collapsed`, `run_detail_steps`, `run_detail_step_expanded`,
|
|
`run_detail_sticky_section` (a `Steps, expanded` header pinned mid-list),
|
|
`pipeline_detail_sections`, `pipeline_detail_section_collapsed`,
|
|
`pipeline_graph_panned` and `pipeline_graph_fit`. `adb logcat` for the app
|
|
package contained no `FATAL EXCEPTION` or Compose/other runtime exception during
|
|
the sweep. As before, `adb` cannot synthesise a two-finger pinch, so the
|
|
centroid-anchored zoom is verified primarily by the `zoomAbout` unit tests and
|
|
the on-device graph was exercised with pan + "Fit graph to view" only.
|
|
|
|
The tabs / code-block / foldable pass was verified on the same
|
|
`Pixel_Fold_API_36` emulator (dark mode, `adb shell cmd uimode night yes`) against
|
|
the live server: `:app:testDebugUnitTest` reported **60 tests, 0 failures**
|
|
(including new `WindowSizeTest` for `isWideLayout` at 400/600/800 and
|
|
`DetailTabsTest` for the tab lists and `clampTabIndex`) and `:app:assembleDebug`
|
|
succeeded. The debug APK was installed and driven; captures were written to
|
|
`captures/tabs_pass/` (git-ignored): every run-detail tab (`05_run_summary`,
|
|
`06_run_graph`, `07_run_input`, `08_run_output`, `10_run_evidence`,
|
|
`11_run_steps`), every pipeline-detail tab (`01_pipeline_summary`,
|
|
`02_pipeline_graph`, `03_pipeline_source`), a long Input/Output block showing the
|
|
themed card scrolling internally (`07_run_input`/`08_run_output`, whose block
|
|
`ScrollView` measures the 320dp cap), a collapsed inner section
|
|
(`09_run_output_collapsed`, `"input, collapsed"`), a step's expanded evidence code
|
|
blocks (`12_run_step_expanded`) and the wide two-pane layouts with the vertical
|
|
tab rail (`13_wide_runs_split`, `14_wide_run_summary`, `15_wide_pipelines_split`,
|
|
`16_wide_pipeline_summary`, `17_wide_pipeline_graph`). Tab-selection persistence
|
|
across a configuration change was exercised by switching `wm density` 390→401
|
|
with the run detail open; the selected tab stayed selected
|
|
(`18_before_config`, `18_after_config`). `adb logcat` for the app package
|
|
contained no `FATAL EXCEPTION` and no Compose/other runtime exception.
|
|
|
|
Because `adb` cannot physically fold the phone, the wide two-pane/rail layout was
|
|
exercised on the emulator by resizing the emulated display (`adb shell wm size
|
|
2000x3400`, ≈820dp at density 390) and the narrow single-pane layout at the
|
|
default width (1080px ≈ 443dp); the attached Pixel 10 Pro Fold was not used to
|
|
drive the app. Note that `:app:installDebug` installs to *every* connected
|
|
device: that Gradle task therefore also (re)installed the debug APK on the
|
|
attached Pixel 10 Pro Fold; all device-driving commands targeted the emulator
|
|
serial (`adb -s emulator-5554`) explicitly. The emulator was stopped with
|
|
`adb emu kill` plus `kill -9` of the surviving `qemu-system-aarch64-headless`.
|