diff --git a/android/README.md b/android/README.md index d2887d52..49c9221e 100644 --- a/android/README.md +++ b/android/README.md @@ -58,6 +58,29 @@ gradle :app:installDebug adb shell am start -n net.awan.pipelines/.MainActivity ``` +### Capturing screenshots + +Never write `adb … screencap` to a file through `exec-out` or a redirect: on a +device with more than one display (e.g. the fold emulator's inner and cover +panels) `screencap` prints a `[Warning] Multiple displays were found…` line to +stderr, adb folds it into the stream, and the `.png` ends up 100+ KB of text +while `adb` still exits 0. Such a file must never be cited as evidence. Capture +on the device to a file, pull it, name the display explicitly, and validate the +bytes before use: + +```sh +android/scripts/capture_png.sh -s # capture + validate +android/scripts/capture_png.sh --check # validate an existing file +``` + +The helper resolves the primary SurfaceFlinger display id (`dumpsys +SurfaceFlinger --display-id`, the id `screencap -d` expects - not the logical +`dumpsys display` id), captures `-d ` to `/sdcard`, pulls, and checks the +PNG magic bytes (and the reported type). A file that is not a real image is +deleted and the helper exits non-zero, so a bad capture stops the run with +`blocked` instead of reaching an approval. Every UI-capturing run must use this +helper and state in its evidence that each image was validated. + ## Configuration Open the **Settings** tab and enter: diff --git a/android/scripts/capture_png.sh b/android/scripts/capture_png.sh new file mode 100755 index 00000000..316be715 --- /dev/null +++ b/android/scripts/capture_png.sh @@ -0,0 +1,179 @@ +#!/usr/bin/env bash +# capture_png.sh - capture a validated PNG screenshot from an Android device. +# +# Why this exists: `adb ... screencap` written straight to a file (through +# `exec-out` or a stdout redirect) is not trustworthy. On a device with more +# than one display - e.g. the fold emulator, which exposes the inner and cover +# panels - screencap prints +# +# [Warning] Multiple displays were found, but no display id was specified! +# +# to stderr, adb folds that into the stream, and the ".png" becomes 100+ KB of +# text while adb still exits 0. A text file must never be cited as screenshot +# evidence. This helper captures on the device to a file, pulls it, names the +# display explicitly when more than one exists, and verifies the pulled bytes +# really are a PNG before returning success. +# +# Usage: +# capture_png.sh -s SERIAL OUT.png capture and validate; non-zero on any +# failure (and the bad file is removed) +# capture_png.sh --check FILE.png validate an existing file only +# capture_png.sh -h this help +# +# Set ADB to override the adb binary, otherwise PATH and the Android SDK +# locations are tried. Resolution of the display id uses the SurfaceFlinger +# ids that `screencap -d` actually expects, not the logical `dumpsys display` +# ids. +set -euo pipefail + +PNG_MAGIC=89504e470d0a1a0a # \x89PNG\r\n\x1a\n + +prog=$(basename "$0") +VALIDATE_REASON="" + +die() { printf '%s: %s\n' "$prog" "$*" >&2; exit 1; } + +usage() { + sed -n '3,20p' "$0" | sed 's/^# \{0,1\}//' +} + +find_adb() { + if [ -n "${ADB:-}" ]; then + printf '%s\n' "$ADB" + return + fi + if command -v adb >/dev/null 2>&1; then + command -v adb + return + fi + local sdk + for sdk in "${ANDROID_HOME:-}" "${ANDROID_SDK_ROOT:-}" "$HOME/Library/Android/sdk"; do + if [ -n "$sdk" ] && [ -x "$sdk/platform-tools/adb" ]; then + printf '%s\n' "$sdk/platform-tools/adb" + return + fi + done + die "adb not found; set ADB or ANDROID_HOME" +} + +# validate_png FILE - return 0 only for a real PNG; on failure set +# VALIDATE_REASON to a short explanation. +validate_png() { + local file=$1 magic + VALIDATE_REASON="" + magic=$(od -An -tx1 -N8 "$file" 2>/dev/null | tr -d ' \n') + if [ ! -s "$file" ]; then + VALIDATE_REASON="file is missing or empty" + return 1 + fi + if [ "$magic" != "$PNG_MAGIC" ]; then + if head -c 9 "$file" | grep -q '^\[Warning\]'; then + VALIDATE_REASON="screencap warning text, not an image" + else + VALIDATE_REASON="magic bytes ${magic:-none} are not a PNG" + fi + return 1 + fi + if command -v file >/dev/null 2>&1 && ! file -b "$file" | grep -q '^PNG image'; then + VALIDATE_REASON="reported type is '$(file -b "$file")', not a PNG image" + return 1 + fi + return 0 +} + +# resolve_display_id ADB SERIAL - print the SurfaceFlinger id of the primary +# display (HWC display 0) so a multi-display device cannot emit the warning. +resolve_display_id() { + local adb=$1 serial=$2 ids primary + ids=$("$adb" -s "$serial" shell dumpsys SurfaceFlinger --display-id 2>/dev/null || true) + primary=$(printf '%s\n' "$ids" | sed -n 's/^Display \([0-9][0-9]*\) (HWC display 0):.*/\1/p' | head -1) + if [ -z "$primary" ]; then + primary=$(printf '%s\n' "$ids" | sed -n 's/^Display \([0-9][0-9]*\):.*/\1/p' | head -1) + fi + printf '%s\n' "$primary" +} + +capture() { + local serial=$1 out=$2 adb primary remote rc count + [ -n "$serial" ] || die "-s SERIAL is required (never capture from an unspecified device)" + case $out in + *.png) ;; + *) die "output must end in .png: $out" ;; + esac + adb=$(find_adb) + primary=$(resolve_display_id "$adb" "$serial") + count=$("$adb" -s "$serial" shell dumpsys SurfaceFlinger --display-id 2>/dev/null | grep -c '^Display [0-9]' || true) + + remote="/sdcard/.capture_png_$$_$(basename "$out")" + if [ -n "$primary" ]; then + rc=0 + "$adb" -s "$serial" shell screencap -p -d "$primary" "$remote" || rc=$? + else + rc=0 + "$adb" -s "$serial" shell screencap -p "$remote" || rc=$? + fi + if [ "$rc" -ne 0 ]; then + "$adb" -s "$serial" shell rm -f "$remote" >/dev/null 2>&1 || true + die "on-device screencap failed (exit $rc)" + fi + "$adb" -s "$serial" pull "$remote" "$out" >/dev/null || { + "$adb" -s "$serial" shell rm -f "$remote" >/dev/null 2>&1 || true + die "pull of $remote failed" + } + "$adb" -s "$serial" shell rm -f "$remote" >/dev/null 2>&1 || true + + if ! validate_png "$out"; then + rm -f "$out" + die "$out is not a real image ($VALIDATE_REASON); deleted - refusing to use it as evidence" + fi + + printf 'validated %s: PNG, %s bytes, %s display(s), display id %s; captured on device to file then pulled\n' \ + "$out" "$(wc -c < "$out" | tr -d ' ')" "$count" "${primary:-default}" +} + +check() { + local file=$1 + [ -f "$file" ] || die "no such file: $file" + if validate_png "$file"; then + printf 'valid %s: PNG, %s bytes\n' "$file" "$(wc -c < "$file" | tr -d ' ')" + else + die "$file is not a real image ($VALIDATE_REASON); refusing to use it as evidence" + fi +} + +serial="" +file="" +action=capture +while [ $# -gt 0 ]; do + case $1 in + -s) + serial=${2:-} + [ -n "$serial" ] || die "-s requires a serial" + shift 2 + ;; + --check) + action=check + file=${2:-} + [ -n "$file" ] || die "--check requires a file" + shift 2 + ;; + -h|--help) + usage + exit 0 + ;; + -*) + die "unknown option $1" + ;; + *) + file=$1 + shift + ;; + esac +done + +[ -n "$file" ] || die "no output file given (see -h)" +if [ "$action" = check ]; then + check "$file" +else + capture "$serial" "$file" +fi