keepassgo/.codex/skills/keepassgo-apk-test/SKILL.md

name, description

name	description
keepassgo-apk-test	Build and run the KeePassGO Android APK for emulator testing. Use when work requires `make apk`, APK install/launch, emulator validation, or checking known KeePassGO Android regressions such as black screens, clipboard, open flow, or local sync behavior.

KeePassGO APK Test

Use this skill together with the installed android-emulator-debug skill. That skill covers generic emulator and adb mechanics. This skill adds the KeePassGO-specific build, install, and validation requirements that have already been established in this repo.

Use This Skill When

• Building build/keepassgo.apk.
• Installing or launching KeePassGO in the Android emulator.
• Verifying Android regressions such as black screen, clipboard, open flow, file picker, or Advanced Sync behavior.
• Checking whether a Gio or Android toolchain change broke runtime behavior.

Known Working Environment

• Preferred emulator AVD: KeepassGoAPI35
• Package: org.julianfamily.keepassgo
• Activity: org.gioui.GioActivity
• Local APK build defaults: ANDROID_SDK_ROOT=/opt/android-sdk ANDROID_NDK_ROOT=/opt/android-ndk JAVA_HOME=/usr/lib/jvm/java-25-openjdk
• CI APK build uses: ANDROID_SDK_ROOT=/opt/android-sdk ANDROID_NDK_ROOT=/opt/android-sdk/ndk JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

Known Regression

• gioui.org v0.9.0 caused a black screen in the KeepassGoAPI35 emulator.
• gioui.org v0.8.0 rendered correctly in the same environment.
• If Android rendering regresses after a Gio change, treat Gio as a primary suspect and verify against this known-bad versus known-good history before guessing about app logic.

Safety Rules

• Do not clobber the user’s real KeePassGO state while testing.
• For host-side validation, use isolated state such as: KEEPASSGO_STATE_DIR="$(mktemp -d)" go test ./...
• Prefer sanitized demo or test vaults when seeding emulator tests.
• If a real vault is absolutely required to reproduce a problem, do not modify it and do not overwrite the user’s existing recent-vault state.

Build Workflow

1. Verify the JDK/SDK paths match the known working environment.
2. Build with make apk for debug validation, or make apk-release when validating production signing behavior.
3. If the build fails, inspect the effective JAVA_HOME, ANDROID_SDK_ROOT, and ANDROID_NDK_ROOT before changing code.
4. If the problem is Android-only, avoid desktop-only conclusions from go test ./....

Typical local build:

JAVA_HOME=/usr/lib/jvm/java-25-openjdk make apk

Typical local release build:

JAVA_HOME=/usr/lib/jvm/java-25-openjdk make apk-release

Emulator Workflow

1. Reuse an existing emulator session if one is already running.
2. Prefer the KeepassGoAPI35 AVD.
3. Install with adb install -r build/keepassgo.apk.
4. Launch with:

adb shell monkey -p org.julianfamily.keepassgo -c android.intent.category.LAUNCHER 1

5. Confirm focus before drawing conclusions:

adb shell dumpsys window | rg 'mCurrentFocus|mFocusedApp'

6. Capture evidence before editing code: screenshot focused window relevant logcat

Validation Checklist

• APK builds successfully with the intended target: make apk for debug validation or make apk-release for release-signing validation.
• App launches to org.julianfamily.keepassgo/org.gioui.GioActivity.
• Screenshot shows the expected screen, not just a black frame.
• logcat shows no app crash or Android runtime fatal error.
• If the change is about user interaction, perform the tap-through in the emulator instead of stopping at install success.

Issue-Specific Checks

Black Screen

• Confirm the app is focused.
• Capture a screenshot and logcat before changing anything.
• Compare the current Gio version against the known v0.9.0 regression history.
• If needed, test whether a minimal Gio example renders in the same emulator before blaming KeePassGO layout code.

Clipboard

• Verify behavior in the emulator, not just unit tests.
• Android clipboard writes must use the Gio-native command path, not desktop clipboard backends.

File Picker Or Local Sync

• Verify the picker flow on Android itself.
• Prefer document-stream or content-URI based behavior over raw filesystem paths when Android permissions are involved.

Report Back

When closing out work, state:

• the exact build command used
• whether the emulator session was reused or newly started
• whether install succeeded
• whether the app actually rendered
• what was verified manually in the emulator
• what remains unverified