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
• A native-Git runtime scaffold with in-memory fallback while no bundled Git binary is present
• 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)

Native Git prototype status

The app now includes a filesystem-backed runtime scaffold for moving from the custom Kotlin Git emulator toward a real native Git backend.

Current prototype behavior:

• the app prepares per-level sandbox directories in app-private storage
• terminal commands are routed through a runtime abstraction instead of directly calling the old in-memory engine
• if a bundled native Git binary is available at runtime, Git commands are executed against a real repository sandbox
• if no bundled native Git binary is present yet, the app automatically falls back to the existing in-memory sandbox so development can continue

Planned native Git packaging path:

• cross-compile Git for Android ABIs with the NDK
• bundle one binary payload per ABI
• extract the correct executable into app-private storage on first launch
• keep helper shell-like commands (ls, pwd, cat, touch, mkdir, rm, echo) implemented in Kotlin

Next steps toward full GitHug parity

• Replace the fallback in-memory Git engine with a packaged native Git binary
• Expand real repository-backed level validation beyond init, add, and commit
• 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