MindMachine/DEVELOPMENT.md

MindMachine - Development Notes

Build prerequisites

Use the root build tooling so local builds and Gitea Actions run through the same script:

./BuildTool.sh --setup-only
./BuildTool.sh --no-commit --apk-only
./BuildTool.sh --no-commit --with-aab

Behavior summary:

• --setup-only prepares the local Android SDK/tooling and exits.

• --apk-only builds the debug APK.

• --with-aab also builds the release AAB.

• --no-commit skips the post-build git commit step.

• Local builds increment versionCode and versionName.

• CI can provide CI_VERSION_CODE to force the build version code and CI_ARTIFACT_TIMESTAMP to control the release AAB filename.

• Artifacts are copied into dist/.

• JDK 17

• Android Studio (recommended)

• Android SDK installed

• local.properties configured (Android Studio usually writes this)

Build outputs (where files end up)

• Debug APK

  • Task: assembleDebug
  • Output: app/build/outputs/apk/debug/app-debug.apk

• Release AAB (Android App Bundle)

  • Task: bundleRelease
  • Output: app/build/outputs/bundle/release/app-release.aab

• Debug AAB (rarely needed)

  • Task: bundleDebug
  • Output: app/build/outputs/bundle/debug/app-debug.aab

Create an AAB (CLI)

Before uploading a new AAB to Google Play, make sure the app version is bumped:

• app/build.gradle.kts → defaultConfig.versionCode must be unique and increasing on Play Console.
• Update versionName as your human-readable release string.

From the repo root:

cd MindMachine
./gradlew bundleRelease

The bundle will be at:

app/build/outputs/bundle/release/app-release.aab

(Optional) clean rebuild:

./gradlew clean bundleRelease

Create an AAB (Android Studio)

1. Build → Generate Signed Bundle / APK…
2. Select Android App Bundle
3. Select Release
4. Select the upload keystore
5. Finish

Signing setup (release bundles)

Release signing is configured in app/build.gradle.kts to load credentials from:

• keystore/upload-keystore.properties

That file should contain the standard fields:

storeFile=keystore/<your-upload-keystore>.jks
storePassword=<password>
keyAlias=<alias>
keyPassword=<password>

Notes:

• Treat upload-keystore.properties as secret. Do not share it publicly.
• On Google Play you typically use Play App Signing. You upload with your upload key, Google signs for distribution.

Play Billing testing (subscribe/buy) checklist

Important: Billing only works reliably when the app is installed from Google Play (Internal/Closed testing). Sideloaded builds often fail Billing flows.

1. Play Console

   • Create your in-app products and/or subscriptions (base plans/offers).
   • Make sure each product is in an Active state.

2. Add testers

   • Add your tester Gmail(s) to the app’s Internal testing (or Closed testing) track.
   • Also add the same Gmail(s) to Play Console → Setup → License testing.

3. Upload AAB + publish to the test track

   • Upload the latest app-release.aab to the test track.
   • Publish/roll out the test release.

4. Install from Play Store

   • On the device, log into the Play Store using the tester account.
   • Install the app from the test track (Play will show it as available to that tester).

5. Payment profile / payment method (if prompted)

   • If Google prompts for payment info on the tester account, add a payment method in:
     • Play Store → Payments & subscriptions → Payment methods
     • (and/or set up the Google Payments profile for that account)
   • Test purchases will use Google’s test purchase flow (no real charge).

6. Verify in the app

   • Trigger the subscribe/buy flow and confirm the purchase dialog appears.
   • Confirm acknowledgements/entitlements are applied as expected.

Billing logging (ADB)

Billing logs are written to Android's system log (Logcat), not displayed in the app UI.

To view billing logs:

# View only MindMachine billing logs
adb logcat -s MindMachineBilling:D

# Filter with silence for other tags
adb logcat -s MindMachineBilling:D *:S

Example log lines you'll see:

• Billing setup finished: 0 OK
• Product details loaded: 2 items
• Query purchases returned X items
• Active entitlement: true/false
• Entitlement changed: false -> true

Billing log tags:

• MindMachineBilling for debug/info messages
• Errors use Log.e() and appear as E/MindMachineBilling in logcat