joe/Githug-Android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Misc Changes

Browse Source
This commit is contained in:
Joe Tretter
2026-05-06 21:28:44 -05:00
parent 5727022baf
commit e1b2d7f7a1
64 changed files with 1662 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@@ -1,34 +1,27 @@
# 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**.
Native Android adaptation of the Ruby [Githug](https://github.com/Gazler/githug) learning game, built with **Kotlin + Jetpack Compose**. The product goal is a shippable mobile implementation that preserves GitHug's CLI-first learning style while making repository state easier to inspect on a phone.
## Current MVP scope
## Implementation Strategy
This repository contains a starter Android app with:
The app is organized around GitHug parity rather than simplified command quizzes:
- 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
- The level catalog follows the upstream Ruby Githug order from `Githug::Level::LEVELS`.
- Each exercise lives in its own Kotlin source file under `app/src/main/java/solutions/tretter/githugandroid/levels/`.
- Each level file documents the intended repository setup, evaluation strategy, hints, command suggestions, and embedded solution scenarios.
- Validators prefer repository state and Git objects over raw command text. Direct command-answer validation is reserved for upstream answer-style levels such as identifying a hash, filename, remote URL, author, or count.
- Shared tests execute the embedded solution scenarios for every level and assert that the Android catalog still matches the upstream level order.
- The runtime prepares an isolated sandbox per level. When a bundled native Git binary is present, Git commands run against real repository directories; otherwise the Kotlin fallback engine keeps development and tests deterministic.
## Product direction
The UI supports a terminal-centered workflow with optional inspection panes:
The app supports three modes:
- **CLI ONLY**: hide visualization and play with terminal-style input.
- **HYBRID**: command line with optional repository panels.
- **VISUAL**: repository panels visible by default, still backed by the same command engine.
- **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
## Development Workflow
## 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
```
Development tasks should be run through the project tooling script. It provisions the local toolchain, keeps paths project-relative, and runs Gradle with the project configuration expected by this repository.
## Android project tooling
@@ -46,15 +39,19 @@ It is designed to be idempotent and uses project-relative paths to:
- install required Android SDK packages
- write `local.properties`
To also build the debug APK without leaving Gradle running in the background:
To run the JVM unit test suite after ensuring the local toolchain is ready:
```bash
bash ./AndroidProjectTooling.sh --test
```
To build the debug APK:
```bash
bash ./AndroidProjectTooling.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.
The script 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:
@@ -62,47 +59,40 @@ To avoid repeated expensive SDK verification, the script writes a small state fi
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:
When `--build` is used, the script also:
```bash
bash ./AndroidProjectTooling.sh --build
```
- increments `versionCode` by 1
- increments the patch component of `versionName`, for example `0.1.0` to `0.1.1`
- renames the debug APK to `githug-android-debug.apk`
- attempts to create a git commit after a successful build if there are source changes
the script will also attempt to create a **git commit after a successful build** if there are source changes to commit.
## Runtime Architecture
It will also automatically bump the Android app version in `app/build.gradle.kts` before each build by:
The command engine has two execution paths behind one app-facing runtime:
- incrementing `versionCode` by 1
- incrementing the patch component of `versionName` (for example `0.1.0` → `0.1.1`)
- **Native Git path**: if the packaged executable is present for the device ABI, Git commands execute in a real per-level repository sandbox in app-private storage.
- **Kotlin fallback path**: the in-memory sandbox engine mirrors the same observable repository facts for development, JVM tests, and environments without a bundled native Git binary.
To run the JVM unit test suite after ensuring the local toolchain is ready:
Both paths expose the same `RepoState` surface to validators. In addition to files, commits, branches, tags, remotes, and config, the model tracks learning-relevant effects such as stashes, fetched remote refs, pushed branches/tags, submodules, and repository maintenance actions.
```bash
bash ./AndroidProjectTooling.sh --test
```
Helper shell-like commands (`ls`, `pwd`, `cat`, `touch`, `mkdir`, `rm`, `echo`, `cd`) remain implemented in Kotlin so the mobile terminal behaves consistently across devices.
## Native Git prototype status
## Level Authoring
The app now includes a **filesystem-backed runtime scaffold** for moving from the custom Kotlin Git emulator toward a real native Git backend.
When adding or changing a level:
Current prototype behavior:
- Keep one source file per exercise.
- Keep `allGithugLevels()` in upstream Ruby Githug order.
- Document the setup and validation intent in the level file.
- Prefer validators that inspect `RepoState` over validators that match command strings.
- Add multiple `LevelTestCase` scenarios when more than one solution path should be accepted.
- Run `bash ./AndroidProjectTooling.sh --test` before building.
- 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
## Production Focus
Planned native Git packaging path:
Current work is focused on:
- 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
- improving parity with upstream Ruby Githug setup and validation semantics
- expanding native-Git-backed behavior across complex repository workflows
- preserving robust fallback tests for every level
- improving onboarding, accessibility, UI polish, icons, and Play Store readiness