feat: semi-automatic Root wizard with Magisk boot patching (v1.0.7)

Adds the semi-automatic Root wizard: extract boot/init_boot from a
user-supplied firmware package, patch it with components taken from the
pinned official Magisk APK, and flash it after backup, ADB-to-fastboot
identity verification, unlock/layout checks and explicit confirmation.

This is a deliberate exception to the read-only stance: the wizard writes
only an evidence-backed boot / init_boot image. It never unlocks the
bootloader and never touches system, vendor, vbmeta, recovery or super.

Patch flags are probed on the device with official Magisk's own app_init
(app_functions.sh) and passed to boot_patch.sh as environment variables.
This is not optional: boot_patch.sh silently defaults a missing flag to
false and ends in a bare `true`, so its exit code proves nothing. On a
system-as-root device KEEPVERITY=false strips `logical` and
`first_stage_mount` off the /system fstab entry, leaving first-stage init
unable to mount the root filesystem — a guaranteed bootloop. Verified on
a real Redmi Note 9 5G (cannon, MT6853, Android 12/MIUI 14): with the
probed flags the patcher reproduces the official Magisk app's output
byte-for-byte; without them it does not.

As defence in depth, the patched image's own config is read back out of
the ramdisk and compared against the probed flags before the image is
allowed anywhere near the flash step. Neither the exit code nor a header
check can catch a wrongly-flagged image — it is structurally valid.

Bumps every aligned version field to 1.0.7 and points the README device
screenshot at the image that actually exists (v1.0.5); it had referenced
a v1.0.6 file that was never added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: backspace135

.github/workflows/publish.yml

@@ -84,6 +84,10 @@ jobs:
         shell: pwsh
         run: ./tools/verify-scrcpy-latest.ps1
 
+      - name: Verify Root tool release pins
+        shell: pwsh
+        run: ./tools/verify-roottools-latest.ps1
+
   package:
     name: Package ${{ matrix.product }} ${{ matrix.rid }}
     runs-on: ${{ matrix.os }}
@@ -167,6 +171,98 @@ jobs:
 
           Write-Host "Verified macOS ZIP contains $appName."
 
+      - name: Verify package integrity and Root tools isolation
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Add-Type -AssemblyName System.IO.Compression.FileSystem
+
+          $zip = Get-ChildItem -Path artifacts -Filter '*.zip' | Select-Object -First 1
+          if ($null -eq $zip) {
+            throw 'No ZIP artifact was produced.'
+          }
+
+          $sidecarPath = "$($zip.FullName).sha256"
+          if (-not (Test-Path -LiteralPath $sidecarPath)) {
+            throw "ZIP '$($zip.Name)' is missing its SHA-256 sidecar."
+          }
+
+          $sidecar = (Get-Content -LiteralPath $sidecarPath -Raw).Trim()
+          if ($sidecar -notmatch '^([0-9a-fA-F]{64}) \*([^\\/\r\n]+)$') {
+            throw "SHA-256 sidecar for '$($zip.Name)' has an invalid format."
+          }
+
+          $expectedHash = $Matches[1].ToLowerInvariant()
+          $expectedName = $Matches[2]
+          $actualHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $zip.FullName).Hash.ToLowerInvariant()
+          if ($expectedName -ne $zip.Name -or $expectedHash -ne $actualHash) {
+            throw "SHA-256 sidecar does not match ZIP '$($zip.Name)'."
+          }
+
+          $product = '${{ matrix.product }}'
+          $rid = '${{ matrix.rid }}'
+          $appPrefix = if ($rid -eq 'osx-arm64') { 'AndroidTreeView.app/Contents/MacOS/' } else { '' }
+          $archive = [System.IO.Compression.ZipFile]::OpenRead($zip.FullName)
+          try {
+            $entries = @($archive.Entries | ForEach-Object { $_.FullName })
+          } finally {
+            $archive.Dispose()
+          }
+
+          if ($rid -eq 'win-x64') {
+            $executable = if ($product -eq 'Mini') { 'AndroidTreeView.App.mini.exe' } else { 'AndroidTreeView.App.exe' }
+            $requiredWindowsEntries = @(
+              $executable,
+              'release.json',
+              'scrcpy/scrcpy.exe',
+              'scrcpy/adb.exe'
+            )
+            foreach ($entry in $requiredWindowsEntries) {
+              if ($entries -notcontains $entry) {
+                throw "Windows ZIP '$($zip.Name)' is missing required entry '$entry'."
+              }
+            }
+          }
+
+          $rootEntries = @($entries | Where-Object { $_ -match '(^|/)root-tools/' })
+          if ($product -eq 'Mini') {
+            if ($rootEntries.Count -ne 0) {
+              throw "Mini ZIP '$($zip.Name)' contains App-only Root tools: $($rootEntries -join ', ')."
+            }
+            Write-Host "Verified Mini ZIP does not contain root-tools/."
+            exit 0
+          }
+
+          $payloadExecutable = if ($rid -eq 'win-x64') { 'payload-dumper-go.exe' } else { 'payload-dumper-go' }
+          $fastbootExecutable = if ($rid -eq 'win-x64') { 'fastboot.exe' } else { 'fastboot' }
+          $requiredEntries = @(
+            "${appPrefix}scrcpy/$fastbootExecutable",
+            "${appPrefix}root-tools/magisk/Magisk-v30.7.apk",
+            "${appPrefix}root-tools/payload-dumper/$payloadExecutable"
+          )
+          foreach ($entry in $requiredEntries) {
+            if ($entries -notcontains $entry) {
+              throw "App ZIP '$($zip.Name)' is missing required Root tool '$entry'."
+            }
+          }
+
+          if ($rid -eq 'osx-arm64') {
+            $extractDir = Join-Path $env:RUNNER_TEMP 'root-tools-mode-check'
+            New-Item -ItemType Directory -Force -Path $extractDir | Out-Null
+            & unzip -q $zip.FullName -d $extractDir
+            if ($LASTEXITCODE -ne 0) {
+              throw "Could not extract '$($zip.FullName)' to verify executable mode."
+            }
+
+            $payloadPath = Join-Path $extractDir "${appPrefix}root-tools/payload-dumper/$payloadExecutable"
+            & /usr/bin/test -x $payloadPath
+            if ($LASTEXITCODE -ne 0) {
+              throw "macOS payload-dumper-go is not executable in '$($zip.Name)'."
+            }
+          }
+
+          Write-Host "Verified App ZIP contains fastboot, Magisk, and payload-dumper-go."
+
       - name: Upload package artifact
         uses: actions/upload-artifact@v7
         with:

.gitignore

@@ -54,6 +54,10 @@ coverage*.info
 # ---- Bundled tooling (Android platform-tools, fetched at build time) ----
 tools/*
 !tools/verify-scrcpy-latest.ps1
+!tools/verify-roottools-latest.ps1
+
+# ---- Local agent/tooling config ----
+.claude/
 
 # ---- OS cruft ----
 .DS_Store

AGENTS.md

@@ -103,7 +103,11 @@ Key architectural rules (see `docs/architecture.md` for the full binding type/in
 - Views use **compiled bindings** (`x:DataType`) and bind only to members that exist on the VM. No
   business logic or ADB calls in views.
 - **No hardcoded user-facing strings.** Use localization for every user-visible string (see below).
-- **Read-only / safe by design**: do not introduce ADB commands that modify, wipe, or flash a device.
+- **Safe by design**: device inspection remains read-only. The only write exception is the dedicated
+  semi-automatic Root wizard, which may install the pinned Magisk APK and flash only an evidence-backed
+  `boot` / `init_boot` image after backup, ADB-to-fastboot identity verification, unlock/layout checks,
+  and two explicit confirmations. Never automate bootloader unlock, erase/format, or other partitions.
+  Real flash is gated only by those in-app confirmations; there is no environment-variable override.
 - Keep files under ~400 lines; the App never crashes on normal ADB/device errors — map them to friendly
   `ErrorMessage` state.
 
@@ -117,7 +121,7 @@ Chinese**; English is the neutral/fallback resource.
   in `AndroidTreeView.Core/Options/SettingsEnums.cs`. `Get` returns the key itself if a resource is
   missing, so a missing translation is visible, not a crash.
 - **Implementation**: `LocalizationService` in `src/AndroidTreeView.App/Localization`, backed by two ResX
-  files with **identical key sets** (keep them in sync — currently 217 keys each):
+  files with **identical key sets** (keep them in sync — currently 329 keys each):
   - `src/AndroidTreeView.App/Resources/Strings.resx` — English (neutral fallback)
   - `src/AndroidTreeView.App/Resources/Strings.zh-Hans.resx` — Simplified Chinese (default)
   - Keys are dotted/namespaced: `app.title`, `nav.devices`, `common.refresh`, etc.
@@ -146,13 +150,14 @@ Fixtures are **inline `const` strings** inside the test classes, not external `.
   `UpdateInstaller`, using test doubles in `TestDoubles.cs`.
 - **`App.Tests`** — ViewModel logic with fake services (`Fakes.cs`): device-list reconcile keeps
   selection, RawProperties filtering, Logcat bounding, DI graph resolves (`ServiceGraphTests`), and a boot
-  smoke test via `Avalonia.Headless` (`TestAppBuilder.cs`, `BootSmokeTests.cs`). No real ADB, no on-screen
-  rendering.
+  smoke test via `Avalonia.Headless` (`TestAppBuilder.cs`, `BootSmokeTests.cs`). Root wizard tests cover
+  device locking, both confirmation gates, retry/partial-write states, localization, and compiled bindings.
+  No real ADB, no on-screen rendering.
 
 ## Versioning & updates
 
 Version is unified across runtime version, App/Mini assembly versions, manifests, and
-`packaging/build-update-zip.ps1` — keep them in sync when bumping (currently `1.0.6`). Update channels:
+`packaging/build-update-zip.ps1` — keep them in sync when bumping (currently `1.0.7`). Update channels:
 `android-tree-view-app` (App) and `android-tree-view-mini` (Mini). `GitHubUpdateService` checks the latest
 GitHub Release, compares semver, and selects the matching product asset; `UpdateInstaller` downloads,
 verifies SHA-256, unpacks the x64 ZIP, and runs a local update script. Loose ZIPs without a supported
@@ -162,3 +167,6 @@ verifies SHA-256, unpacks the x64 ZIP, and runs a local update script. Loose ZIP
 
 `build/AndroidTreeView.Scrcpy.targets` downloads and bundles scrcpy (which ships adb) into `tools/scrcpy`
 at build/publish time on Windows. `tools/verify-scrcpy-latest.ps1` checks for newer scrcpy releases.
+The full App also imports `build/AndroidTreeView.RootTools.targets`, which pins and verifies the official
+Magisk APK and payload-dumper-go for `win-x64` / `osx-arm64`. Mini variants never import or ship Root tools.
+Fastboot comes from pinned Android SDK Platform-Tools 37.0.0 and is hash-verified before packaging.

build/AndroidTreeView.RootTools.targets

@@ -0,0 +1,103 @@
+<Project>
+
+  <!-- Root workflow tools are App-only. Mini projects must never import this target. -->
+  <PropertyGroup>
+    <MagiskVersion Condition="'$(MagiskVersion)' == ''">30.7</MagiskVersion>
+    <MagiskAssetName Condition="'$(MagiskAssetName)' == ''">Magisk-v$(MagiskVersion).apk</MagiskAssetName>
+    <MagiskUrl Condition="'$(MagiskUrl)' == ''">https://github.com/topjohnwu/Magisk/releases/download/v$(MagiskVersion)/$(MagiskAssetName)</MagiskUrl>
+    <MagiskSha256 Condition="'$(MagiskSha256)' == ''">e0d32d2123532860f97123d927b1bb86c4e08e6fd8a48bfc6b5bee0afae9ebd5</MagiskSha256>
+
+    <PayloadDumperVersion Condition="'$(PayloadDumperVersion)' == ''">1.3.0</PayloadDumperVersion>
+    <PayloadDumperPlatform Condition="'$(RuntimeIdentifier)' == 'win-x64'">windows_amd64</PayloadDumperPlatform>
+    <PayloadDumperPlatform Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">darwin_arm64</PayloadDumperPlatform>
+    <PayloadDumperExecutableName Condition="'$(RuntimeIdentifier)' == 'win-x64'">payload-dumper-go.exe</PayloadDumperExecutableName>
+    <PayloadDumperExecutableName Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">payload-dumper-go</PayloadDumperExecutableName>
+    <PayloadDumperSha256 Condition="'$(RuntimeIdentifier)' == 'win-x64'">0f96e07477963327f7f50a03bf2aa9dac5c76dba110ab332dc759321ae345d52</PayloadDumperSha256>
+    <PayloadDumperSha256 Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">e6b95df4b08e4bf452077e35cc2c0d644ce8fd454696d1aceedde6887ef0df84</PayloadDumperSha256>
+    <PayloadDumperExecutableSha256 Condition="'$(RuntimeIdentifier)' == 'win-x64'">cd017857a28d029e80b0830531bcc960be5bbd4b8c937b122024285197012cd7</PayloadDumperExecutableSha256>
+    <PayloadDumperExecutableSha256 Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">56d5dd0f402cecc2548a563d840f3fd9e707521b5bd398430f59894c79d08450</PayloadDumperExecutableSha256>
+    <PayloadDumperAssetName Condition="'$(PayloadDumperPlatform)' != ''">payload-dumper-go_$(PayloadDumperVersion)_$(PayloadDumperPlatform).tar.gz</PayloadDumperAssetName>
+    <PayloadDumperUrl Condition="'$(PayloadDumperUrl)' == '' and '$(PayloadDumperAssetName)' != ''">https://github.com/ssut/payload-dumper-go/releases/download/$(PayloadDumperVersion)/$(PayloadDumperAssetName)</PayloadDumperUrl>
+
+    <RootToolsDir Condition="'$(RootToolsDir)' == ''">$(IntermediateOutputPath)root-tools</RootToolsDir>
+    <RootToolsDownloadDir>$(IntermediateOutputPath)root-tools-download</RootToolsDownloadDir>
+    <AndroidTreeViewBundleRootTools Condition="'$(AndroidTreeViewBundleRootTools)' == ''">true</AndroidTreeViewBundleRootTools>
+    <_RootToolsSupportedRid Condition="'$(RuntimeIdentifier)' == 'win-x64' or '$(RuntimeIdentifier)' == 'osx-arm64'">true</_RootToolsSupportedRid>
+  </PropertyGroup>
+
+  <Target Name="AtvEnsureRootTools" BeforeTargets="Build;Publish"
+          Condition="'$(AndroidTreeViewBundleRootTools)' == 'true' and '$(_RootToolsSupportedRid)' == 'true' and (!Exists('$(RootToolsDir)/magisk/$(MagiskAssetName)') or !Exists('$(RootToolsDir)/payload-dumper/$(PayloadDumperExecutableName)'))">
+    <Message Importance="high" Text="AndroidTreeView: fetching verified App-only Root tools for $(RuntimeIdentifier)..." />
+    <MakeDir Directories="$(RootToolsDownloadDir);$(RootToolsDownloadDir)/payload-extract;$(RootToolsDir)/magisk;$(RootToolsDir)/payload-dumper" />
+
+    <DownloadFile SourceUrl="$(MagiskUrl)" DestinationFolder="$(RootToolsDownloadDir)"
+                  DestinationFileName="$(MagiskAssetName)" Retries="1">
+      <Output TaskParameter="DownloadedFile" PropertyName="_MagiskDownload" />
+    </DownloadFile>
+    <GetFileHash Files="$(RootToolsDownloadDir)/$(MagiskAssetName)" Algorithm="SHA256" HashEncoding="hex">
+      <Output TaskParameter="Items" ItemName="_MagiskHash" />
+    </GetFileHash>
+    <Error Condition="'%(_MagiskHash.FileHash)' != '$(MagiskSha256)'"
+           Text="Magisk SHA-256 mismatch: expected $(MagiskSha256), got %(_MagiskHash.FileHash)." />
+    <Copy SourceFiles="$(RootToolsDownloadDir)/$(MagiskAssetName)"
+          DestinationFiles="$(RootToolsDir)/magisk/$(MagiskAssetName)" />
+
+    <DownloadFile SourceUrl="$(PayloadDumperUrl)" DestinationFolder="$(RootToolsDownloadDir)"
+                  DestinationFileName="$(PayloadDumperAssetName)" Retries="1">
+      <Output TaskParameter="DownloadedFile" PropertyName="_PayloadDumperDownload" />
+    </DownloadFile>
+    <GetFileHash Files="$(RootToolsDownloadDir)/$(PayloadDumperAssetName)" Algorithm="SHA256" HashEncoding="hex">
+      <Output TaskParameter="Items" ItemName="_PayloadDumperHash" />
+    </GetFileHash>
+    <Error Condition="'%(_PayloadDumperHash.FileHash)' != '$(PayloadDumperSha256)'"
+           Text="payload-dumper-go SHA-256 mismatch: expected $(PayloadDumperSha256), got %(_PayloadDumperHash.FileHash)." />
+    <Exec Command="tar -xzf &quot;$(RootToolsDownloadDir)/$(PayloadDumperAssetName)&quot; -C &quot;$(RootToolsDownloadDir)/payload-extract&quot;" />
+    <Copy SourceFiles="$(RootToolsDownloadDir)/payload-extract/$(PayloadDumperExecutableName)"
+          DestinationFiles="$(RootToolsDir)/payload-dumper/$(PayloadDumperExecutableName)" />
+    <Exec Condition="'$(RuntimeIdentifier)' == 'osx-arm64'"
+          Command="chmod +x &quot;$(RootToolsDir)/payload-dumper/$(PayloadDumperExecutableName)&quot;" />
+
+    <Error Condition="!Exists('$(RootToolsDir)/magisk/$(MagiskAssetName)')"
+           Text="Verified Magisk asset was not copied to the Root tools layout." />
+    <Error Condition="!Exists('$(RootToolsDir)/payload-dumper/$(PayloadDumperExecutableName)')"
+           Text="Verified payload-dumper-go asset was not copied to the Root tools layout." />
+  </Target>
+
+  <Target Name="AtvVerifyRootTools" BeforeTargets="Build;Publish" DependsOnTargets="AtvEnsureRootTools"
+          Condition="'$(AndroidTreeViewBundleRootTools)' == 'true' and '$(_RootToolsSupportedRid)' == 'true'">
+    <Error Condition="!Exists('$(RootToolsDir)/magisk/$(MagiskAssetName)') or !Exists('$(RootToolsDir)/payload-dumper/$(PayloadDumperExecutableName)')"
+           Text="Root tools are incomplete for $(RuntimeIdentifier)." />
+    <GetFileHash Files="$(RootToolsDir)/magisk/$(MagiskAssetName)" Algorithm="SHA256" HashEncoding="hex">
+      <Output TaskParameter="Items" ItemName="_VerifiedMagiskHash" />
+    </GetFileHash>
+    <GetFileHash Files="$(RootToolsDir)/payload-dumper/$(PayloadDumperExecutableName)" Algorithm="SHA256" HashEncoding="hex">
+      <Output TaskParameter="Items" ItemName="_VerifiedPayloadDumperHash" />
+    </GetFileHash>
+    <Error Condition="'%(_VerifiedMagiskHash.FileHash)' != '$(MagiskSha256)'"
+           Text="Cached Magisk SHA-256 mismatch: expected $(MagiskSha256), got %(_VerifiedMagiskHash.FileHash)." />
+    <Error Condition="'%(_VerifiedPayloadDumperHash.FileHash)' != '$(PayloadDumperExecutableSha256)'"
+           Text="Cached payload-dumper-go SHA-256 mismatch: expected $(PayloadDumperExecutableSha256), got %(_VerifiedPayloadDumperHash.FileHash)." />
+  </Target>
+
+  <Target Name="AtvCopyRootToolsToOutput" AfterTargets="Build"
+          Condition="'$(AndroidTreeViewBundleRootTools)' == 'true' and '$(_RootToolsSupportedRid)' == 'true' and Exists('$(RootToolsDir)')">
+    <ItemGroup>
+      <_RootToolsOut Include="$(RootToolsDir)/**/*" />
+    </ItemGroup>
+    <Copy SourceFiles="@(_RootToolsOut)"
+          DestinationFiles="@(_RootToolsOut->'$(OutDir)root-tools/%(RecursiveDir)%(Filename)%(Extension)')"
+          SkipUnchangedFiles="true" />
+  </Target>
+
+  <Target Name="AtvCopyRootToolsToPublish" BeforeTargets="ComputeFilesToPublish"
+          Condition="'$(AndroidTreeViewBundleRootTools)' == 'true' and '$(_RootToolsSupportedRid)' == 'true' and Exists('$(RootToolsDir)')">
+    <ItemGroup>
+      <_RootToolsPub Include="$(RootToolsDir)/**/*" />
+      <ResolvedFileToPublish Include="@(_RootToolsPub)">
+        <RelativePath>root-tools/%(_RootToolsPub.RecursiveDir)%(_RootToolsPub.Filename)%(_RootToolsPub.Extension)</RelativePath>
+        <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
+      </ResolvedFileToPublish>
+    </ItemGroup>
+  </Target>
+
+</Project>