magisk-app

name	magisk-app
description	Guidelines, architecture, development conventions, and build workflows for the Magisk Android application (app/ subproject). Use when working on, modifying, building, or testing code in app/ or any of its submodules (:core, :apk-ng, :shared, :stub, :stub-res, :test, :build-logic, :apk).

Magisk App Subproject Guidelines

Guidelines and workflows for developing and building the Android application in the app/ subproject.

1. Environment & Gradle Setup

• General Guidelines: Always follow the top-level AGENTS.md and magisk-git for repository rules, environment execution setup, and commit control policies.
• Working Directory: Set working directory to app/ when running standalone Gradle commands, or execute build commands via ./build.py from the repository root.
• Environment Wrapper: Standalone ./gradlew commands MUST be prefixed with ../scripts/env.py (e.g., ../scripts/env.py ./gradlew :apk-ng:assembleDebug). Alternatively, run ./build.py app-ng from the repository root (which configures the environment automatically and builds :apk-ng).

2. Architecture & Submodules

Multi-module Gradle project structure:

• :apk-ng (apk-ng/): Next-gen app variant. Primary target for UI and application features.
• :core (core/): Core domain logic, resources, Room DB, services. Primary target for core feature development.
• :shared (shared/): Shared utilities and common data structures.
• :stub (stub/): Lightweight stub app loader for hidden installs.
• :stub-res (stub-res/): Stub-specific Android resources.
• :test (test/): Application testing target.
• :build-logic (build-logic/): Custom Gradle plugins and build logic.
• :apk (apk/): Legacy app APK. Maintenance mode: Do NOT modify unless explicitly requested.

3. Development Guidelines

• Target Modules: All active app development occurs in :core and :apk-ng. Do NOT make changes to :apk unless explicitly requested.
• Legacy Compatibility: When modifying :core and :shared, make sure the :apk module is still buildable.
• Language & UI: Written in Kotlin/Java. Prefer Kotlin for all new code. Uses Jetpack Compose for UI (prefer over View XML).
• String Resources: Default strings in core/src/main/res/values/strings.xml and stub-res/src/main/res/values/strings.xml. Translations go in values-[lang]/strings.xml.
• Data Stack: Room, KSP, Wire (Protocol Buffers), Moshi.

4. Workflows & Verification

From app/ directory (prefixed with ../scripts/env.py):

• Build App (:apk-ng Debug): ../scripts/env.py ./gradlew :apk-ng:assembleDebug
• Build Stub APK: ../scripts/env.py ./gradlew :stub:assembleDebug
• Build Legacy APK (:apk Debug): ../scripts/env.py ./gradlew :apk:assembleDebug
• Run Lint: ../scripts/env.py ./gradlew lint (or ../scripts/env.py ./gradlew :apk-ng:lintDebug)
• Run Unit Tests: ../scripts/env.py ./gradlew test
• Clean Artifacts: ../scripts/env.py ./gradlew clean

From repository root (via build.py):

• Build App (:apk-ng): ./build.py app-ng
• Build Stub App: ./build.py stub
• Build Legacy App (:apk): ./build.py app
• Run App Tests: ./build.py test