# 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:

```bash
./gradlew assembleDebug
```

## Automated environment setup

This repo includes a root-level setup script:

```bash
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
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
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