108 lines
6.3 KiB
Markdown
108 lines
6.3 KiB
Markdown
# The Android app — working map
|
|
|
|
Read this before touching `android/`. It is the project-specific half; how Android projects in
|
|
general are built, tested and reviewed belongs to the pipeline that started you.
|
|
|
|
## Build and test (offline, never with the daemon)
|
|
|
|
This checkout has no `gradlew`; the toolchain uses the installed distribution:
|
|
|
|
```sh
|
|
# Run these commands from the repository root.
|
|
export JAVA_HOME='/Applications/Android Studio.app/Contents/jbr/Contents/Home'
|
|
export ANDROID_HOME="$HOME/Library/Android/sdk"
|
|
GRADLE=/Users/alan/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/bin/gradle
|
|
"$GRADLE" -p android --offline --no-daemon :app:assembleDebug # ~7 s incremental
|
|
"$GRADLE" -p android --offline --no-daemon :app:testDebugUnitTest # 400+ tests, ~8-13 s
|
|
```
|
|
|
|
Always `--no-daemon`: a leftover daemon is what makes these look slow. Add **one** test class at a
|
|
time while iterating — the full suite is for the end.
|
|
|
|
## Devices and the resource pool
|
|
|
|
The ADB executable is `/Users/alan/Library/Android/sdk/platform-tools/adb`.
|
|
Use that absolute path (or explicitly add its directory to PATH); `adb: command
|
|
not found` alone is not evidence that the leased device is disconnected.
|
|
|
|
For populated attention review, `TestExportReadyAttentionReviewFixture` exports a
|
|
create-only scratch database when `PIPELINES_ATTENTION_REVIEW_DIR` names a new
|
|
directory. Its fixture.json identifies one failed, one finished and one waiting
|
|
run and the workspace. Build a scratch server, read back those states, and keep
|
|
the owned server alive through all UI interactions. The export itself does not
|
|
leave a server running or configure a device. Never use a dead scratch endpoint.
|
|
|
|
Only the **UI reviewer**, while its stage holds the runner-granted resource for its
|
|
visit, may use a device. Implementers and code reviewers do code, builds, unit
|
|
tests and source review only: **no adb, installs, captures, device-setting changes
|
|
or main-build restoration**. Never acquire a device using sleep/check loops. The
|
|
runner grants exactly one concrete member of the `android-devices` resource pool
|
|
and passes it to the stage as `resource_target`; take the `adb -s` target from
|
|
`resource_target.metadata.adb_serial` and do not choose a device yourself.
|
|
|
|
The pool's two members are:
|
|
|
|
- `phone-47241FDAS00DLK` — the operator's **Pixel 9 Pro XL**, adb serial
|
|
`47241FDAS00DLK` (metadata `kind=phone`).
|
|
- `emulator-Pipelines_Fold_A` — one managed **foldable emulator**, adb serial
|
|
`emulator-5554` (metadata `kind=emulator`, `avd=Pipelines_Fold_A`). Its unfolded
|
|
built-in display is 2076x2152; its cover display is 1080x2424.
|
|
|
|
The operator's **Pixel 10 Pro Fold** (`58281FDCG000JF`) is delivery-only: never a
|
|
test target. Do not start an ad-hoc emulator — the one managed foldable AVD above
|
|
is the only emulator in scope.
|
|
|
|
The UI reviewer records original app connection/workspace, display size and power/settings
|
|
before changing them. Before any capture: `svc power stayon usb`, `settings put global stay_on_while_plugged_in 7`,
|
|
`input keyevent KEYCODE_WAKEUP`, `wm dismiss-keyguard`. Capture with
|
|
`adb -s <serial> shell screencap -p /sdcard/shot.png` then `adb pull` — never `exec-out > file`.
|
|
Wide layout: `wm size 2000x2244`; the fold's unfolded shape is `wm size 2076x2152`; `wm size reset`
|
|
afterwards either way.
|
|
|
|
Create controlled fixtures for changed screens/states (including human-decision sheets)
|
|
on a scratch server/database and throwaway session; never depend on incidental production
|
|
state, change a real operator session, or restart a deployed service. Use the configured
|
|
authoritative endpoint, never a scratch URL as a project default. Keep all shell/ADB work
|
|
foreground and awaited: no detached/background processes may outlive the lease.
|
|
UI review includes restoring the captured original settings and main's build before its
|
|
successful return. Confirm every tool has exited. If capture, restoration or cleanup fails,
|
|
report the failure explicitly; do not claim verification or readiness. Uncertain termination
|
|
must fail closed and keep ownership quarantined, not delete a lock or expire it by age.
|
|
Return `output.resource_cleanup_confirmed=false` if restoration/readiness is uncertain;
|
|
that generic release veto retains the runner lease even if the harness reports idle.
|
|
|
|
## Geometry is tokenised, and a test enforces it
|
|
|
|
Every dimension comes from `ui/theme/Dimens.kt` (plus the layout itself) — no new hardcoded `dp`, no
|
|
percentages. `DimensTest` fails the build for a raw literal outside that file, so a value that
|
|
genuinely needs a new token goes there, named for its purpose.
|
|
|
|
## Where things are
|
|
|
|
- `ui/PipelinesApp.kt` — the app shell: destinations, the floating pill, the omni-search morph.
|
|
- `ui/chat/` — the chat: `ChatScreen`/`ChatTranscript`/`ChatComposer` (list, transcript, composer),
|
|
`ChatStore` (multi-conversation state), `ChatFormat` (parts → rendering), `ChatOverrides` (local
|
|
rename/hide), `Markdown`, `ChatScroll`.
|
|
- `ui/screens/` — `PipelineListScreen`, `PipelineDetailScreen`, `RunHistoryScreen`, `RunDetailScreen`,
|
|
`SettingsScreen`, `Timeline`.
|
|
- `ui/graph/` — the workflow graph, stage panes, artifacts gallery and viewer.
|
|
- `ui/components/` — `ListRow`, `DetailTabs`, `PaneIdentity`, `RunStatus`, `AttentionSurface`.
|
|
- `data/` — `PipelinesRepository` (the socket client) and `data/protocol/` (wire shapes).
|
|
- The app talks to the Pipelines server over the websocket in `data/PipelinesRepository.kt`; live run
|
|
state arrives as pushed `run_event` frames, and every view that shows run state folds them.
|
|
|
|
## Publishing a build
|
|
|
|
Copy the APK into the running run's artifacts directory as `pipelines-debug-wip-<short-HEAD>.apk` and
|
|
report the LAN URL. The UI reviewer alone, under the same lease, restores **main's** build after an install:
|
|
`/private/var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/opencode/deploy-app.sh main`.
|
|
|
|
## Traps
|
|
|
|
- A build made in a worktree that is behind main is missing features main has — sync before building,
|
|
and say which revision you built.
|
|
- Restore the app's captured original connection and workspace after a fixture test,
|
|
using the configured authoritative endpoint; then force-stop and relaunch under the lease.
|
|
Never substitute a hardcoded or disposable scratch endpoint for the original configuration.
|
|
- `mStayOn`/screen timeout are already set; do not "fix" the device by locking or sleeping it.
|