Mafza

Emergency actions runner with one configurable profile, external emergency triggers, and a safe Dry Run mode.

Screenshots

English	Arabic (RTL)
Home (preflight + run controls)	Home (الصفحة الرئيسية)
Profile (actions + policies)	Profile (الإعدادات)
Action Drawer (available actions)	Action Drawer (لوحة الإجراءات)
History (runs + statuses)	History (السجل)

What This App Does

• Runs emergency pipelines in Live or Dry Run.
• Supports external trigger surfaces: launcher shortcut, home widget, and Quick Settings tile.
• Uses a pre-start cancel window and preflight checks before live execution.
• Sends communication actions via SMS, message-app provider bindings, and Telegram bot actions.
• Supports custom intent actions as executable steps.
• Supports destructive actions with explicit allowlists:
  • uninstall package allowlist
  • absolute-path delete allowlist
  • advanced shell commands
• Uses Shizuku for privileged destructive actions (uninstall, self-uninstall, advanced shell).
• Supports path-delete fallback via Android All files access when Shizuku is unavailable.
• Captures run history with step-level statuses and redacted command audit.
• Supports encrypted backup/restore for profile and optional history (replace semantics).
• Captures cell metadata and supports optional OpenCellID fallback when platform location is unavailable.

Requirements

• Android minSdk 30 (Android 11+)
• Runtime permissions for configured live features (ACCESS_FINE_LOCATION, ACCESS_BACKGROUND_LOCATION, READ_PHONE_STATE, SEND_SMS)
• MANAGE_EXTERNAL_STORAGE (All files access) when path-delete actions are enabled without Shizuku
• Shizuku installed/running and permission granted for privileged destructive live actions (uninstall, advanced shell, self-uninstall)
• Optional OpenCellID API key for location fallback

Architecture

Core pieces:

• :app and :core modules
• MainActivity: Compose host for Home, Profile, History
• EmergencyExecutionService: foreground execution runtime and run orchestration
• EmergencyStartReceiver: shared external trigger receiver
• EmergencyShortcutProxyActivity, EmergencyWidgetProvider, EmergencyQuickSettingsTileService: trigger surfaces
• PreflightValidator: live/dry-run readiness checks
• EncryptedProfileStore + DataStore: encrypted profile persistence
• RunHistoryStore + Room: run history and command audit retention
• EncryptedBackupService: encrypted export/import with rollback on restore failure
• EmergencyStepsFactory + step implementations: location, notify, intent, and destructive execution

Build

This project uses mise for tool management.

# Build debug APK
./gradlew :app:assembleDebug

# Build release APK
./gradlew :app:assembleRelease

# Run app + core unit tests
./gradlew :core:testDebugUnitTest :app:testDebugUnitTest

# Build instrumentation test APK
./gradlew :app:assembleDebugAndroidTest

Fastlane And Metadata

This repo includes:

• fastlane/metadata/android/en-US
• fastlane/metadata/android/ar
• screenshot assets under fastlane/metadata/android/*/images/phoneScreenshots
• lanes for metadata validation, screenshot capture, and Play upload

Useful commands:

# Install fastlane gems
bundle install

# Validate metadata
bundle exec fastlane android validate_metadata

# Capture screenshots
bundle exec fastlane android capture_screenshots

CI

GitHub Actions workflows:

• ci.yml: lint, unit tests, assemble, instrumentation subset, metadata validation
• Linux emulator jobs enable KVM acceleration before running instrumentation
• screenshots.yml: emulator-based screenshot capture and optional PR
• release.yml: version/tag flow, screenshot refresh dependency, release artifacts, optional GitHub release

Dependency updates are managed by renovate.json5.

Internal Docs

• Product/technical plan: docs/PLAN.md
• Release checklist: docs/RELEASE_CHECKLIST.md
• Remaining tasks: docs/TODO.md