diff --git a/.codex/skills/keepassgo-apk-test/SKILL.md b/.codex/skills/keepassgo-apk-test/SKILL.md new file mode 100644 index 0000000..b6e4e73 --- /dev/null +++ b/.codex/skills/keepassgo-apk-test/SKILL.md @@ -0,0 +1,116 @@ +--- +name: keepassgo-apk-test +description: 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`. +3. If `make apk` 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: + +```sh +JAVA_HOME=/usr/lib/jvm/java-25-openjdk make apk +``` + +## 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: + +```sh +adb shell monkey -p org.julianfamily.keepassgo -c android.intent.category.LAUNCHER 1 +``` + +5. Confirm focus before drawing conclusions: + +```sh +adb shell dumpsys window | rg 'mCurrentFocus|mFocusedApp' +``` + +6. Capture evidence before editing code: + screenshot + focused window + relevant `logcat` + +## Validation Checklist + +- APK builds successfully with `make apk`. +- 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 diff --git a/AGENTS.md b/AGENTS.md index 1811c6a..97599c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,8 @@ These instructions apply to all future work in this repository. ## Skills - Use the installed Go skills whenever they materially apply to the current slice of work. +- Use the installed `android-emulator-debug` skill for Android emulator lifecycle, `adb`, screenshots, and log capture work. +- Use the repo-local `keepassgo-apk-test` skill for KeePassGO-specific APK build and emulator test runs. - The available Go skills for this repository are: `go-code-review`, `go-concurrency`, @@ -126,6 +128,20 @@ These features are product requirements, not “nice to have” ideas. - Keep `golangci-lint` passing. - Keep `go test ./...` passing. - Track `gogio` as a Go tool and keep a reproducible `make apk` path for Android packaging. +- Keep the Android build requirements aligned with the known working setup: + `ANDROID_SDK_ROOT=/opt/android-sdk`, + local `ANDROID_NDK_ROOT=/opt/android-ndk`, + CI `ANDROID_NDK_ROOT=/opt/android-sdk/ndk`, + local `JAVA_HOME=/usr/lib/jvm/java-25-openjdk`, + CI `JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64`. +- Remember the known Android runtime regression: + `gioui.org v0.9.0` produced a black screen on the `KeepassGoAPI35` emulator, while `gioui.org v0.8.0` rendered correctly. Treat Gio upgrades on Android as regression-sensitive and verify them on-device or in the emulator. +- When validating an APK in the emulator, prefer the known KeePassGO setup: + AVD `KeepassGoAPI35`, + package `org.julianfamily.keepassgo`, + activity `org.gioui.GioActivity`. +- Do not run emulator/manual APK tests against the user’s real persisted app state. + Use an isolated `KEEPASSGO_STATE_DIR` for host-side validation, and when emulator testing requires seeded vault data, use sanitized test/demo vaults rather than the user’s real vault files whenever possible. - When running tests or other automated validation that may touch persisted UI state, set `KEEPASSGO_STATE_DIR` to an isolated temporary directory so recent-vault history and other local state do not pollute the user’s real config. - Prefer commands shaped like `KEEPASSGO_STATE_DIR=\"$(mktemp -d)\" go test ./...` for ad hoc local validation unless a test already manages its own isolated state directory. - Do not assume the agent can decrypt SOPS-encrypted secrets in this repository.