fix: harden shell runtime, stabilize app flows, and sync native docs/CI

Author: risunCode

.github/workflows/build.yml

@@ -7,53 +7,18 @@ on:
     branches: [main]
 
 jobs:
-  build-web:
-    name: Build React
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-          cache-dependency-path: web/package-lock.json
-
-      - name: Install dependencies
-        working-directory: ./web
-        run: npm ci
-
-      - name: Build React
-        working-directory: ./web
-        run: npm run build
-
-      - name: Upload web assets
-        uses: actions/upload-artifact@v4
-        with:
-          name: web-assets
-          path: app/src/main/assets/www
-          retention-days: 1
-
   build-android:
-    name: Build Android
-    needs: build-web
+    name: Lint, Test, and Build Debug APK
     runs-on: ubuntu-latest
     permissions:
       contents: read
+
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Download web assets
-        uses: actions/download-artifact@v4
-        with:
-          name: web-assets
-          path: app/src/main/assets/www
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
       - name: Setup JDK 17
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9
         with:
           java-version: '17'
           distribution: 'temurin'
@@ -62,51 +27,19 @@ jobs:
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew
 
-      # 1. Debug Build
-      - name: Build Debug APK
+      - name: Run lint
+        run: ./gradlew lintDebug --no-daemon
+
+      - name: Run unit tests
+        run: ./gradlew testDebugUnitTest --no-daemon
+
+      - name: Build debug APK
         run: ./gradlew assembleDebug --no-daemon
 
-      - name: Upload Debug APK
-        uses: actions/upload-artifact@v4
+      - name: Upload debug APK
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
         with:
           name: AppControlX-debug
           path: app/build/outputs/apk/debug/*.apk
-          retention-days: 7
-
-      # 2. Release Build (Logic to handle both Real Sign and Generated Sign)
-      - name: Configure Keystore
-        id: sign_config
-        run: |
-          if [ -n "${{ secrets.KEYSTORE_BASE64 }}" ]; then
-            echo "Found secrets. Setting up Real Signing..."
-            echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > release.keystore
-            echo "KEYSTORE_FILE=$(pwd)/release.keystore" >> $GITHUB_ENV
-            echo "KEYSTORE_PASSWORD=${{ secrets.KEYSTORE_PASSWORD }}" >> $GITHUB_ENV
-            echo "KEY_ALIAS=${{ secrets.KEY_ALIAS }}" >> $GITHUB_ENV
-            echo "KEY_PASSWORD=${{ secrets.KEY_PASSWORD }}" >> $GITHUB_ENV
-            echo "build_type=real-signed" >> $GITHUB_OUTPUT
-          else
-            echo "No secrets found. Setting up Generated Signing..."
-            keytool -genkey -v -keystore release.keystore -alias androiddebugkey -keyalg RSA -keysize 2048 -validity 10000 -storepass android -keypass android -dname "CN=Android Debug,O=Android,C=US"
-            echo "KEYSTORE_FILE=$(pwd)/release.keystore" >> $GITHUB_ENV
-            echo "KEYSTORE_PASSWORD=android" >> $GITHUB_ENV
-            echo "KEY_ALIAS=androiddebugkey" >> $GITHUB_ENV
-            echo "KEY_PASSWORD=android" >> $GITHUB_ENV
-            echo "build_type=generated-signed" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Build Release APK
-        run: ./gradlew assembleRelease --no-daemon
-
-      - name: Rename Release APK
-        run: |
-          cd app/build/outputs/apk/release/
-          # Find the release apk (it might include version number)
-          find . -name "*release.apk" -exec mv {} AppControlX-release-${{ steps.sign_config.outputs.build_type }}.apk \;
-
-      - name: Upload Release APK
-        uses: actions/upload-artifact@v4
-        with:
-          name: AppControlX-release-${{ steps.sign_config.outputs.build_type }}
-          path: app/build/outputs/apk/release/*.apk
+          if-no-files-found: error
           retention-days: 7

.github/workflows/release.yml

@@ -7,32 +7,23 @@ on:
 
 jobs:
   build-and-release:
-    name: Build and Release
+    name: Build Signed Release and Publish
     runs-on: ubuntu-latest
     permissions:
       contents: write
 
+    env:
+      KEYSTORE_BASE64: ${{ secrets.KEYSTORE_BASE64 }}
+      KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
+      KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+      KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-          cache-dependency-path: web/package-lock.json
-
-      - name: Install web dependencies
-        working-directory: ./web
-        run: npm ci
-
-      - name: Build React
-        working-directory: ./web
-        run: npm run build
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
       - name: Setup JDK 17
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9
         with:
           java-version: '17'
           distribution: 'temurin'
@@ -41,31 +32,50 @@ jobs:
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew
 
-      - name: Decode Keystore
-        if: env.KEYSTORE_BASE64 != ''
-        env:
-          KEYSTORE_BASE64: ${{ secrets.KEYSTORE_BASE64 }}
+      - name: Validate signing secrets
+        shell: bash
         run: |
-          echo "$KEYSTORE_BASE64" | base64 --decode > app/keystore.jks
+          set -euo pipefail
+          missing=()
+          [ -n "$KEYSTORE_BASE64" ] || missing+=("KEYSTORE_BASE64")
+          [ -n "$KEYSTORE_PASSWORD" ] || missing+=("KEYSTORE_PASSWORD")
+          [ -n "$KEY_ALIAS" ] || missing+=("KEY_ALIAS")
+          [ -n "$KEY_PASSWORD" ] || missing+=("KEY_PASSWORD")
+
+          if [ ${#missing[@]} -gt 0 ]; then
+            echo "Release signing is required. Missing secrets: ${missing[*]}"
+            exit 1
+          fi
 
-      - name: Build Release APK
+      - name: Decode keystore
+        shell: bash
+        run: |
+          set -euo pipefail
+          KEYSTORE_PATH="$RUNNER_TEMP/release.keystore"
+          echo "$KEYSTORE_BASE64" | base64 --decode > "$KEYSTORE_PATH"
+          echo "KEYSTORE_FILE=$KEYSTORE_PATH" >> "$GITHUB_ENV"
+
+      - name: Build signed release APK
         run: ./gradlew assembleRelease --no-daemon
         env:
-          KEYSTORE_FILE: ${{ github.workspace }}/app/keystore.jks
-          KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
-          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
-          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+          KEYSTORE_FILE: ${{ env.KEYSTORE_FILE }}
+          KEYSTORE_PASSWORD: ${{ env.KEYSTORE_PASSWORD }}
+          KEY_ALIAS: ${{ env.KEY_ALIAS }}
+          KEY_PASSWORD: ${{ env.KEY_PASSWORD }}
 
-      - name: Get version from tag
-        id: version
-        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+      - name: Upload release artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: AppControlX-release
+          path: app/build/outputs/apk/release/*.apk
+          if-no-files-found: error
+          retention-days: 30
 
-      - name: Create Release
-        uses: softprops/action-gh-release@v1
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@26994186c0ac3ef5cae75ac16aa32e8153525f77
         with:
-          name: AppControlX ${{ steps.version.outputs.version }}
-          files: |
-            app/build/outputs/apk/release/*.apk
+          name: AppControlX ${{ github.ref_name }}
+          files: app/build/outputs/apk/release/*.apk
           generate_release_notes: true
           draft: false
           prerelease: false

CHANGELOG.md

@@ -50,7 +50,7 @@ This is a complete migration from WebView/React to full native Kotlin with Jetpa
 - **activity_main.xml** - Layout XML removed
 
 ### Technical Details
-- 100% offline, no network calls
+- Native feature execution is local/on-device; the app still declares `INTERNET` permission in manifest
 - All native methods preserved (ShellManager, AppScanner, etc.)
 - Material Design 3 components throughout
 - Edge-to-edge display support
@@ -114,7 +114,7 @@ This is a complete migration from WebView/React to full native Kotlin with Jetpa
 - **Cache Strategy** - 30s TTL for app list, persistent icon cache
 
 ### Technical Details
-- All optimizations are **100% offline** (no network calls)
+- Runtime optimizations are local to device execution paths (no backend dependency)
 - Web layer remains design + UI only
 - Backend remains 100% Kotlin native
 - All 23 native methods intact and functional
@@ -243,7 +243,9 @@ This is a complete rewrite of AppControlX with modern architecture and new featu
 
 ---
 
-## Architecture (v3)
+## Legacy Architecture Context (v3.x)
+
+Historical reference for the v3 release line before the v4 native migration:
 
 ```
 ┌─────────────────────────────────────┐