6.3 KiB
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:
# 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 serial47241FDAS00DLK(metadatakind=phone).emulator-Pipelines_Fold_A— one managed foldable emulator, adb serialemulator-5554(metadatakind=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) anddata/protocol/(wire shapes).- The app talks to the Pipelines server over the websocket in
data/PipelinesRepository.kt; live run state arrives as pushedrun_eventframes, 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.