VibedByKaKi/soul-browser
1
3
Fork 0
Code Issues Pull requests Releases 4 Activity
soul-browser/AGENTS.md
KaKi87 de895672ae
Clean dev builds: testing ID in git, generated artifacts gitignored (#69) 
* Add shared soul2_info module for README INFO extraction.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Use soul2_info module in prepare-info-string.py.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Derive soul2_info_text from README in push-i18n-english.py.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Gitignore generated build_date.xml and soul2_info.xml.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Bootstrap build_date.xml when missing at build time.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Stop tracking generated build_date and soul2_info string resources.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Store testing application ID in tracked app sources.

Canonical tree uses net.kaki87.soul2.testing and Soul2⁺ Browser so
feature-branch builds avoid package rewrites.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Auto-commit libsoulamz prebuilts on main CI builds.

Skip follow-up workflow runs for bundled-warp/lib updates via paths-ignore
and [skip ci] commit message.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Document CI refresh of libsoulamz prebuilts.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Document testing package in git and generated build artifacts.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Document source tree testing ID and build-generated resources.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Gitignore Python __pycache__ directories.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-25 19:32:34 +02:00

3 KiB
Raw Permalink Blame History

AGENTS.md

Cursor Cloud specific instructions

This repo rebuilds a signed Android APK (Soul Browser / “Soul Rebuild”) from Apktool smali sources. There is no web server, package manager, or long-running app service.

Build (primary workflow)

  • Tracked app/ sources use the testing application ID (net.kaki87.soul2.testing, Soul2⁺ Browser). Stable releases (net.kaki87.soul2) are produced only when CI on main sets SOUL_PACKAGE_ID=net.kaki87.soul2 during the build.
  • app/res/values/build_date.xml and app/res/values/soul2_info.xml are generated at build time (gitignored). INFO screen text comes from the README <!-- BEGIN INFO --> block; scripts/prepare-info-string.py writes the XML for Apktool.
  • bundled-warp/lib/*/libsoulamz.so is committed; CI on main auto-commits refreshes when native/soulamz/main.go changes.
  • Run ./scripts/build.sh (see README). Requires Java 21+, curl, zip/unzip, keytool, and Android SDK build-tools with apksigner on PATH (or via ANDROID_HOME / ANDROID_SDK_ROOT).
  • In this environment the SDK lives at $HOME/android-sdk (build-tools 35.0.0). Ensure ANDROID_HOME / ANDROID_SDK_ROOT are set before building.
  • Output: signed APK under dist/ (also intermediate unsigned/aligned copies). Signature schemes v1+v2+v3 are required (targetSdk 36).
  • apktool JAR is auto-downloaded into tools/ by the build script; that directory is gitignored.
  • There is no separate lint/test suite; the practical checks are a successful ./scripts/build.sh plus apksigner verify on the produced APK.

Emulator (nested Cloud Agent VMs)

Do not use -accel on / KVM here. The host hits kernel BUG at arch/x86/kvm/x86.c (kvm_spurious_fault during kvm_arch_vcpu_create). QEMU stays nearly idle and adb never leaves offline. Always boot with -accel off (TCG). Cold boot takes roughly 5–10 minutes.

ABI: The APK’s native libs are ARM-only. Use system-images;android-30;google_apis;x86_64 (NDK translation; ro.product.cpu.abilist includes arm64-v8a,armeabi-v7a). API 33 google_apis x86_64 fails with INSTALL_FAILED_NO_MATCHING_ABIS.

Helper: ./scripts/run-emulator.sh (creates the soul_test AVD if needed, then starts the emulator). Start adb first; avoid pkill -f emulator (it can kill the calling shell). Prefer killall qemu-system-x86_64-headless.

Smoke after boot:

adb wait-for-device
adb shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 2; done'
adb install -r -g dist/soul-browser-*.apk
adb shell am start -a android.intent.action.VIEW -d 'https://example.com/' \
  -n net.kaki87.soul2/com.mycompany.app.web.WebLauncher
# First launch shows onboarding; tap Start (id/splash_apply_view, center ~360,1014 on 720x1280)

For non-main builds the application ID is net.kaki87.soul2.testing. Smoke tests on a stable APK use net.kaki87.soul2 in the am start component name.

System UI may ANR under TCG; dismiss Wait/Close and retry. Prefer build + apksigner verify when on-device UI is not required.