Files
pipelines/android/AGENTS.md
T

3.5 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:

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" --offline --no-daemon :app:assembleDebug        # ~7 s incremental
"$GRADLE" --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.

The dev device

The only device is the operator's Pixel 9 Pro XL, serial 47241FDAS00DLK. The operator's Pixel 10 Pro Fold (58281FDCG000JF) is theirs: use it only where an item's brief explicitly allows it, and never make it a default. Never start or use an emulator.

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.

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. After any install, leave the operator's phone on main's build: /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.
  • Changing the app's server URL for a test (a stub) must be undone: ws://10.0.0.75:8080/connect, workspace /Users/alan/repos/pipelines, then force-stop and relaunch.
  • mStayOn/screen timeout are already set; do not "fix" the device by locking or sleeping it.