# 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
- Full official Githug level catalog, split into dedicated Kotlin level files

## 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`)

## 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
- Tighten advanced real repository-backed validation across the full Githug catalog
- Continue refining per-level setup fidelity for the remaining advanced scenarios
- Add richer validation rules and per-level explanations
- Add onboarding, accessibility polish, icons, tests, and Play Store assets