Githug-Android/README.md

GitHug Android

Native Android adaptation of the GitHug learning game, built with Kotlin + Jetpack Compose and designed for mobile-first usability while preserving a CLI-first play style.

Current MVP scope

This repository contains a starter Android app with:

• Kotlin + Jetpack Compose project scaffolding
• CLI-first gameplay shell
• Optional hideable visualization panel
• In-memory Git sandbox engine for early commands
• First playable GitHug-inspired levels: init, add, and commit

Product direction

The app supports three modes:

• CLI ONLY: hide all visualization and play with terminal-style input only
• HYBRID: command line with optional repo panels
• VISUAL: repo panels visible by default, still backed by the same command engine

Building

You will need a local Android SDK installation and either Android Studio or SDK command line tools.

Typical next step once the SDK is installed:

./gradlew assembleDebug

Automated environment setup

This repo includes a root-level setup script:

bash ./SetupBuildEnvironment.sh

It is designed to be idempotent and uses project-relative paths to:

• install a project-local JDK into ./jdk
• install Android command-line tools into ./android-sdk
• restore gradle/wrapper/gradle-wrapper.jar if missing
• install required Android SDK packages
• write local.properties

To also build the debug APK without leaving Gradle running in the background:

bash ./SetupBuildEnvironment.sh --build

The script and project are configured to prefer non-daemon Gradle usage.

It also avoids depending on the system Java version by provisioning a project-local JDK 17, which is required by current Android SDK command-line tools.

To avoid repeated expensive SDK verification, the script writes a small state file named:

./.setup-build-environment.state

If all required components were verified successfully, the script will skip SDK verification/reinstallation for the next 24 hours unless required directories are missing.

When you run:

bash ./SetupBuildEnvironment.sh --build

the script will also attempt to create a git commit after a successful build if there are source changes to commit.

It will also automatically bump the Android app version in app/build.gradle.kts before each build by:

• incrementing versionCode by 1
• incrementing the patch component of versionName (for example 0.1.0 → 0.1.1)

Next steps toward full GitHug parity

• Expand the Git sandbox to cover merge, rebase, stash, tags, remotes, reset, revert, cherry-pick, bisect, and more
• Port all original levels and hints into structured content files
• Add richer validation rules and per-level explanations
• Add onboarding, accessibility polish, icons, tests, and Play Store assets