feat: overhaul helper scripts and tooling

* move api works to python and restructure python helpers:
- use uv for the python env and package management
- use ruff and basedpyright for python checks
- match release assets with glob patterns

* general changes:
- add dependency checks
- introduce tri-state (auto / true / false) option
- add support for python scripts checking in workflows
- merge some small files together to reduce scripts fragementation

Signed-off-by: bachnxuan <bachnxuan@gmail.com>

Author: bachnxuan

.github/workflows/build.yml

@@ -19,7 +19,7 @@ on:
         type: boolean
         required: true
       STOCK_CONFIG:
-        type: boolean
+        type: string
         required: true
       TG_NOTIFY:
         type: boolean
@@ -56,8 +56,12 @@ on:
 
       STOCK_CONFIG:
         description: "Spoof stock config?"
-        default: true
-        type: boolean
+        default: auto
+        type: choice
+        options:
+          - auto
+          - true
+          - false
 
       TG_NOTIFY:
         description: "Telegram Notify"
@@ -89,7 +93,13 @@ jobs:
         run: |
           sudo apt-get update -qq
           sudo apt-get install -qq \
-            bc bison ccache curl flex git tar wget aria2 jq zip zstd upx build-essential python3-requests libfaketime lz4 just
+            bc bison ccache curl flex git tar wget aria2 jq zip zstd upx build-essential libfaketime lz4 just
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.14
+        run: uv python install 3.14
 
       - name: Compute ccache key
         run: |

.github/workflows/check.yml

@@ -1,20 +1,26 @@
-name: Bash Check
+name: Check
 
 on:
   pull_request:
     paths:
       - "**/*.sh"
+      - "py/**/*.py"
+      - "py/pyproject.toml"
+      - "py/uv.lock"
       - "justfile"
       - ".github/workflows/check.yml"
   push:
     paths:
       - "**/*.sh"
+      - "py/**/*.py"
+      - "py/pyproject.toml"
+      - "py/uv.lock"
       - "justfile"
       - ".github/workflows/check.yml"
   workflow_dispatch:
 
 jobs:
-  check:
+  bash:
     runs-on: ubuntu-latest
 
     steps:
@@ -26,5 +32,24 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y just shellcheck shfmt
 
-      - name: Run checks
-        run: just check
+      - name: Run bash checks
+        run: just fmt-check bash-check lint
+
+  python:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6.0.1
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.14
+        run: uv python install 3.14
+
+      - name: Sync Python dev dependencies
+        run: uv sync --project py --group dev
+
+      - name: Run Python checks
+        run: just py-lint py-check

.github/workflows/release.yml

@@ -57,7 +57,7 @@ jobs:
       KSU: ${{ matrix.variant.KSU }}
       SUSFS: ${{ matrix.variant.SUSFS }}
       LXC: ${{ matrix.variant.LXC }}
-      STOCK_CONFIG: true
+      STOCK_CONFIG: auto
       TG_NOTIFY: false
 
   release:
@@ -77,6 +77,12 @@ jobs:
         with:
           path: release_files
 
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.14
+        run: uv python install 3.14
+
       - name: Import build metadata
         run: |
           metadata_file="release_files/github-metadata-VNL/github.json"
@@ -103,9 +109,9 @@ jobs:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           RELEASE_REPO: ${{ env.RELEASE_REPO }}
         run: |
-          TAG_PY="$GITHUB_WORKSPACE/py/tag.py"
+          UV_PROJECT="$GITHUB_WORKSPACE/py"
 
-          RELEASE_TAG=$(python3 "$TAG_PY" "$RELEASE_REPO")
+          RELEASE_TAG=$(uv run --project "$UV_PROJECT" tools release next-tag "$RELEASE_REPO")
 
           echo "New tag: $RELEASE_TAG"
           echo "RELEASE_TAG=$RELEASE_TAG" >> "$GITHUB_ENV"
@@ -153,7 +159,7 @@ jobs:
           TG_BOT_TOKEN: ${{ secrets.TG_BOT_TOKEN }}
           TG_CHAT_ID: ${{ secrets.TG_CHAT_ID }}
         run: |
-          TG_PY="$GITHUB_WORKSPACE/py/tg.py"
+          UV_PROJECT="$GITHUB_WORKSPACE/py"
         
           escape_md_v2() {
             python3 - "$*" <<'PY'
@@ -173,4 +179,4 @@ jobs:
           EOF
           )
           
-          printf '%s' "$message" | python3 "$TG_PY" msg
+          printf '%s' "$message" | uv run --project "$UV_PROJECT" tools tg msg

.gitignore

@@ -1,5 +1,6 @@
 # Build outputs
 /out/
+/work/
 /boot_image/
 /clang/
 /kernel/
@@ -8,11 +9,23 @@
 /mkbootimg/
 /susfs/
 /staged/
-*.log
+/build.log
 /github.env
 /github.json
 /.ccache/
 /libfakestat/
+
+# Editor state
 /.vscode/
+*.swp
+*.swo
+*~
+
+# Python
 /modules/flatten/
 /modules/staging/
+/py/.venv/
+/py/.python-version
+/py/**/__pycache__/
+/py/.mypy_cache/
+/py/.ruff_cache/

README.md

@@ -10,7 +10,7 @@ pulls sources and tools, applies optional patches, then builds and packages the
 - config.sh: defaults, repos, paths, and target settings
 - build/: setup, patching, and compile kernel
 - ci/: packaging, metadata, modules, and telegram helpers
-- py/: small python helpers
+- py/: uv-managed python helpers
 - modules/: modules.load for xaga modules packaging
 - kernel_patches/: kernel patches
 - .github/workflows/: ci and release workflows
@@ -20,13 +20,13 @@ pulls sources and tools, applies optional patches, then builds and packages the
 ubuntu/debian:
 
 ```bash
-sudo apt install bc bison ccache curl flex git tar wget aria2 jq zip zstd upx build-essential python3-requests libfaketime lz4 just
+sudo apt install bc bison ccache curl flex git tar wget aria2 jq zip zstd upx build-essential libfaketime lz4 just shellcheck shfmt uv
 ````
 
 fedora:
 
 ```bash
-sudo dnf install bc bison ccache curl flex git tar wget aria2 jq zip zstd upx make python3-requests libfaketime lz4 just
+sudo dnf install bc bison ccache curl flex git tar wget aria2 jq zip zstd upx make libfaketime lz4 just ShellCheck shfmt uv
 ```
 
 ## run
@@ -53,6 +53,12 @@ run checks:
 just check
 ```
 
+python type check:
+
+```bash
+just py-check
+```
+
 clean build:
 
 ```bash
@@ -67,7 +73,7 @@ just clean
 | KSU             | enable kernelsu                                | bool |
 | SUSFS           | enable susfs                                   | bool |
 | LXC             | apply the lxc patch, xaga only                 | bool |
-| STOCK_CONFIG    | apply the stock config patch                   | bool |
+| STOCK_CONFIG    | stock config mode                              | str  |
 | BRANCH_OVERRIDE | use a different kernel branch                  | str  |
 | JOBS            | set make job count                             | int  |
 | RESET_SOURCES   | re-clone sources and tools before building     | bool |
@@ -79,6 +85,8 @@ just clean
 notes:
 
 - bool accepts true/false, t/f, yes/no, y/n, on/off, 1/0
+- STOCK_CONFIG accepts `auto`, `true`, or `false`
+- `auto` means off for xaga and on for generic
 - SUSFS needs KSU=true
 - LXC only works with BUILD_TARGET=xaga
 - TG_NOTIFY=true needs TG_BOT_TOKEN and TG_CHAT_ID
@@ -89,7 +97,6 @@ notes:
 | ----------------------------- | ----------------------- |
 | work/                         | kernel out              |
 | out/\<package>-AnyKernel3.zip | flashable package       |
-| out/\<package>-boot.img       | xaga boot image         |
 | out/\<package>-boot-raw.img   | generic raw boot image  |
 | out/\<package>-boot-gz.img    | generic gzip boot image |
 | out/\<package>-boot-lz4.img   | generic lz4 boot image  |

build.sh

@@ -27,33 +27,72 @@ count() {
 }
 
 validate_env() {
-    info "Validating environment variables..."
-    if [[ -z ${GH_TOKEN:-} ]]; then
-        if [[ -x "$CLANG_BIN/clang" ]]; then
-            :
-        elif is_ci; then
-            error "Required Github PAT missing: GH_TOKEN"
-        else
-            warn "GH_TOKEN isn't set, requests may be rate-limited."
-        fi
-    fi
-
-    # Telegram checks
-    if is_true "$TG_NOTIFY"; then
-        : "${TG_BOT_TOKEN:?Required Telegram Bot Token missing: TG_BOT_TOKEN}"
-        : "${TG_CHAT_ID:?Required chat ID missing: TG_CHAT_ID}"
-        export TG_BOT_TOKEN
-        export TG_CHAT_ID
-    fi
-
-    # Config checks
-    if is_true "$SUSFS" && ! is_true "$KSU"; then
-        error "Cannot use SUSFS without KernelSU"
-    fi
+    local stage="$1"
+
+    case "$stage" in
+        github)
+            # before fetching github release assets
+            if [[ -z ${GH_TOKEN:-} ]]; then
+                if [[ -x "$CLANG_BIN/clang" && -f "$LIBFAKESTAT" ]]; then
+                    :
+                elif is_ci; then
+                    error "Required Github PAT missing: GH_TOKEN"
+                else
+                    warn "GH_TOKEN isn't set, requests may be rate-limited."
+                fi
+            fi
+            ;;
+        telegram)
+            # before sending telegram updates
+            if is_true "$TG_NOTIFY"; then
+                : "${TG_BOT_TOKEN:?Required Telegram Bot Token missing: TG_BOT_TOKEN}"
+                : "${TG_CHAT_ID:?Required chat ID missing: TG_CHAT_ID}"
+                export TG_BOT_TOKEN
+                export TG_CHAT_ID
+            fi
+            ;;
+        config)
+            # before build prep
+            if is_true "$SUSFS" && ! is_true "$KSU"; then
+                error "Cannot use SUSFS without KernelSU"
+            fi
+
+            if is_true "$LXC" && [[ $BUILD_TARGET != "xaga" ]]; then
+                error "LXC is not supported for $BUILD_TARGET target"
+            fi
+            ;;
+        *)
+            fatal "Unknown environment validation stage: $stage"
+            ;;
+    esac
+}
 
-    if is_true "$LXC" && [[ $BUILD_TARGET != "xaga" ]]; then
-        error "LXC is not supported for $BUILD_TARGET target"
-    fi
+validate_deps() {
+    local stage="$1"
+
+    case "$stage" in
+        base)
+            # before the build starts
+            require_cmds \
+                aria2c bash ccache chmod cp curl date find git head hexdump make mkdir \
+                python3 rm sed sha256sum sort tar tee uv zip zstd
+            ;;
+        patching)
+            # before applying patches
+            require_cmds patch
+            ;;
+        modules)
+            # before xaga module packaging
+            require_cmds depmod llvm-strip xz
+            ;;
+        bootimg)
+            # before generic boot image packaging
+            require_cmds gzip lz4 unzip
+            ;;
+        *)
+            fatal "Unknown dependency validation stage: $stage"
+            ;;
+    esac
 }
 
 main() {
@@ -62,7 +101,6 @@ main() {
 
     count init_build
     count init_logging
-    count validate_env
     count send_start_msg
     count prepare_dirs
     count fetch_sources

build/all.sh

@@ -3,5 +3,4 @@
 
 source "$WORKSPACE/build/utils.sh"
 source "$WORKSPACE/build/setup.sh"
-source "$WORKSPACE/build/patch.sh"
 source "$WORKSPACE/build/compile.sh"