#+TITLE: Kolahal
#+CAPTION: Kolahal logo
[[file:site/public/favicon.svg]]
#+END_EXPORT
#+SUBTITLE: A keyboard-first terminal launcher for Android
Kolahal (=com.mtwabpin.kolahal=) is a terminal-style home screen for Android 9 and newer. Type a few
letters and press Enter to open an app or run a command; every command and its output is kept in a log. It reads RSS and Atom feeds, keeps todos, notes and reminders, controls media and the device,
runs your own scripts in Lua 5.4 or JavaScript (QuickJS), and works with the work profile and
private space.
#+begin_quote
Kolahal is developed with AI assistance. The developers review every change except the tests.
#+end_quote
Kolahal's code is still under review. It is young (0.4), parts of it were written with AI
assistance, and the review of the codebase as a whole isn't finished. Expect rough edges and changes
between versions, keep a [[https://mtwabpin.github.io/kolahal/guides/backup/][backup]], and report what you find.
- APK: the [[https://github.com/mtwabpin/kolahal/releases/latest][latest release]] on GitHub has the full build, with every feature, and the Play build for Google Play. The [[https://mtwabpin.github.io/kolahal/getting-started/install/][install guide]] explains how to sideload them. The full build supports self-updating.
Important: Google Play Protect blocks sideloaded apps (installed from a browser, a messaging app or a file manager) that declare an accessibility service or notification access, in India and some other countries. Both builds declare notification access, which shows your notifications in the log, and the full build also has an accessibility service, which only locks the screen.
To install, turn off Play Store → profile → Play Protect → ⚙︎ → Scan apps with Play Protect, then turn it back on. Or use adb install. Once Kolahal is on Google Play, installing it from there avoids the block.
- Google Play: in a closed test; [[https://mtwabpin.github.io/kolahal/getting-started/play-testing/][join it]] to install Kolahal from the Play Store. The
Play build leaves out the screen lock, which needs an accessibility declaration on Play, calls in the log, which Play's policy doesn't allow, and =update=, as apps on Play update only through Play.
The user guide is at [[https://mtwabpin.github.io/kolahal/][mtwabpin.github.io/kolahal]].
#+begin_src sh
./gradlew :app:assembleRelease # the full APK
./gradlew :app:bundlePlay # the Google Play bundle (-PplayApk :app:assemblePlay: its APK)
./gradlew :app:testDebugUnitTest # JVM tests
#+end_src
- [[file:docs/developing.org][docs/developing.org]]: building, the architecture, the repository layout and common changes.
- [[file:docs/codebase-guide.org][docs/codebase-guide.org]]: a guided tour of the code, how its parts fit together and why.
- [[file:docs/release/README.org][docs/release/]]: how releases are built, signed and published, on GitHub and Google Play.
- [[file:site/README.md][site/README.md]]: the website, built with Astro and Starlight from =site/=.
Kolahal is built with AI assistance, and contributions may use it too. Vibe coding (changes nobody has read, understood or tested, prompted until something seemed to work) isn't accepted.
AI assistance is fine as long as you stay the author:
- You read every line you send, and can explain what it does and why in review.
- You built it and tried it on a phone or the emulator; the tests pass, and new behaviour has tests.
- You say in the pull request what the AI did.
Pull requests and issues that look generated and unchecked (large unexplained changes, calls to
functions that don't exist, claims nobody verified) are closed without review. The same goes for
bug reports: reproduce the problem yourself first.
JVM unit tests (=app/src/test=) cover pure logic: parsing, ranking, layout maths and formats.
On-device tests (=app/src/androidTest=) cover the script engines and sandbox, commands, storage and
backup, and the home and settings screens. The on-device ones install the debug build (package
suffix =.debug=) and change its settings; run them on an emulator.
Coverage: 90.8% of the app's code lines (0.4.15), counting a line when either kind of test runs it.
It is measured at each release with JaCoCo, on an Android 16 emulator:
#+begin_src sh
./gradlew -Pcoverage :app:createDebugUnitTestCoverageReport :app:createDebugAndroidTestCoverageReport
perl tools/coverage.pl # the total, and each package
#+end_src
