diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 98b3de5..af90abb 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -10,7 +10,7 @@ on: workflow_dispatch: inputs: version: - description: "Release version, for example 1.0.5" + description: "Release version, for example 1.0.6" required: true type: string diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9d6357f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,163 @@ +# AGENTS.md + +This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. + +## What this is + +AndroidTreeView is a **.NET 10 + Avalonia** Windows desktop tool for inspecting, testing and managing +Android devices over ADB. Despite the name it is a C#/.NET solution, **not** a Java/Kotlin Android app. +It has two shipping executables that share the same core: + +- **App** (`src/AndroidTreeView.App`) — the full Avalonia UI: device overview, per-category details, + screen mirroring (scrcpy), CLI tools, settings, updates. +- **Mini** (`src/AndroidTreeView.Mini`) — a lightweight WinForms tray/monitor app that stays resident, + watches for devices, and auto-launches scrcpy once a device is connected and authorized. Mini + deliberately does **not** carry the Avalonia/Skia runtime. + +`Mini.Mac` is an Avalonia-based Mini variant for macOS. + +## Commands + +Requires the **.NET 10 SDK**. Run from the repo root. + +```bash +dotnet restore AndroidTreeView.sln +dotnet build AndroidTreeView.sln +dotnet test AndroidTreeView.sln +dotnet run --project src/AndroidTreeView.App +dotnet run --project src/AndroidTreeView.Mini +``` + +Building on non-Windows (App/Mini target Windows) needs the targeting pack flag — CI uses it everywhere: + +```bash +dotnet build AndroidTreeView.sln -p:EnableWindowsTargeting=true +``` + +Run a single test project / a single test: + +```bash +dotnet test tests/AndroidTreeView.Adb.Tests +dotnet test AndroidTreeView.sln --filter "FullyQualifiedName~BatteryParser" +``` + +Format check (CI runs this, non-blocking — but keep it clean): + +```bash +dotnet format AndroidTreeView.sln --verify-no-changes +``` + +Package/verify the release ZIP link locally (real releases only ship via the GitHub `Publish` workflow, +x64 only): + +```powershell +./packaging/build-update-zip.ps1 -Product App -Rid win-x64 +./packaging/build-update-zip.ps1 -Product Mini -Rid win-x64 +``` + +There are ready-made Rider/VS run configs under `.run/`. + +## Architecture + +The layering is strict and enforced by project references — respect the dependency direction. Lower +layers never reference upper ones. + +``` +Models domain records/enums, no project deps + ↑ +Core interfaces, options (AppSettings, AdbOptions), typed exceptions, DeviceMonitor + ↑ +Adb / Infrastructure Adb: ProcessRunner, command builders, parsers, AdbDeviceService, LogcatService + ↑ Infrastructure: SettingsService (JSON), logging, update check/install +Shared the shared composition root — AddAndroidTreeViewSharedServices() wires ADB, monitoring, + ↑ scrcpy, settings, and update services identically for both App and Mini +App / Mini / Mini.Mac executables (each references Shared) +``` + +Key architectural rules (see `docs/architecture.md` for the full binding type/interface contract, and +`docs/app-contract.md`): + +- **Shared is the single wiring point.** Both App and Mini call + `AddAndroidTreeViewSharedServices(...)` so their ADB/scrcpy/settings/update behavior can't drift. + When adding a service that both should use, register it there (it uses `TryAdd*`), not per-app. +- **App is strict MVVM** with CommunityToolkit.Mvvm (`[ObservableProperty]` / `[RelayCommand]`) and + `Microsoft.Extensions` DI/Hosting/Logging. `Program.cs` builds the host + `IServiceProvider`, then + Avalonia resolves `MainWindowViewModel`. `ViewLocator` maps `*.ViewModels.XxxViewModel` → + `*.Views.XxxView` by name convention. +- **All ADB is out-of-process** via `ProcessRunner` (async stdout/stderr, kills the whole process tree + on cancel/timeout). Device info comes from parsing ADB text output. +- **Parsers are pure and unit-tested.** ADB output parsing lives in `AndroidTreeView.Adb.Parsers` as + stateless/static functions (`GetPropParser`, `BatteryParser`, `AdbDevicesParser`, etc.). Any change to + parsing logic must come with a parser test — fixtures live under the Adb.Tests project. +- `AdbLocator` resolves adb (configured path → PATH → common SDK locations); `IAdbEnvironment` holds the + current location as a singleton. If adb is missing the App shows a Setup page instead of crashing. +- `DeviceMonitor` owns a `PeriodicTimer` background loop and raises `DevicesChanged`; VMs marshal to the + UI thread themselves. + +## Conventions (from `.editorconfig` + `CONTRIBUTING.md`) + +- File-scoped namespaces, 4-space indent, interfaces `I`-prefixed, `using` outside the namespace, + CRLF line endings, UTF-8. +- **Async-only for I/O**: `async` + `CancellationToken` propagated everywhere. No `.Result` / `.Wait()` / + `Task.Run` for ADB/process work. UI mutations only on the UI thread (`Dispatcher.UIThread.Post`). +- 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. +- Keep files under ~400 lines; the App never crashes on normal ADB/device errors — map them to friendly + `ErrorMessage` state. + +## Localization + +Every user-facing string is localized — never hardcode display text. Default language is **Simplified +Chinese**; English is the neutral/fallback resource. + +- **Contract**: `ILocalizationService` (`AndroidTreeView.Core/Interfaces`) — `Get(key)`, `Format(key, args)`, + the `this[key]` indexer, `SetLanguage(AppLanguage)`, and a `LanguageChanged` event. `AppLanguage` lives + 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): + - `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. +- **In ViewModels**: inject `ILocalizationService` and call `_localization.Get("key")` / `.Format(...)`. +- **In XAML**: use the `{loc:Localize Key=some.key}` markup extension (`LocalizeExtension` + + `LocalizeKeyConverter`). Bindings watch `LocalizationService.LanguageTick` so text refreshes live when + the language changes (the indexer's own `INotifyPropertyChanged` was unreliable in this Avalonia + version — that's why the plain `LanguageTick` counter exists; keep using it for live-refresh bindings). + +**When adding a string**: add the key to **both** ResX files, then reference it via `Get`/`Format` (VMs) +or `{loc:Localize}` (XAML). Never add a key to only one file. + +## Tests + +xUnit across four projects (`dotnet test AndroidTreeView.sln`, or target one project — see Commands). +Fixtures are **inline `const` strings** inside the test classes, not external `.txt` files. + +- **`Adb.Tests`** — the bulk of the suite. `Parsers/` has one test class per parser/builder + (`BatteryParserTests`, `StorageParserTests`, `AdbDevicesParserTests`, `GetPropParserTests`, + `RootStatusParserTests`, `NetworkParserTests`, the `*BuilderTests`, etc.), `Commands/` covers argv + building (`AdbArgsTests`), `Services/` covers device-action/screen-capture services. **Any change to ADB + output parsing must add/update the matching parser test here** — this is where correctness is pinned. +- **`Core.Tests`** — `AppSettings` clone/serialize, `DeviceMonitor` start/stop (with a fake + `IDeviceService`), `SemanticVersion`, file-transfer service. +- **`Infrastructure.Tests`** — `SettingsService` persistence, update check (`NekoIndexUpdateService`) and + `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. + +## 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: +`android-tree-view-app` (App) and `android-tree-view-mini` (Mini). `NekoIndexUpdateService` checks the +channel and compares semver; `UpdateInstaller` downloads, verifies SHA-256, unpacks the x64 ZIP, and runs +a local update script. Loose ZIPs without a supported `release.json` manifest are rejected. + +## Bundled tools + +`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. diff --git a/README-CN.md b/README-CN.md index d84bcdd..fba964b 100644 --- a/README-CN.md +++ b/README-CN.md @@ -3,17 +3,17 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-0E7A5F.svg)](LICENSE) [![.NET 10](https://img.shields.io/badge/.NET-10.0-512BD4.svg)](https://dotnet.microsoft.com/) [![Avalonia 11.3](https://img.shields.io/badge/Avalonia-11.3-663399.svg)](https://avaloniaui.net/) -[![Platform: Windows](https://img.shields.io/badge/Platform-Windows-0078D6.svg)](#windows-使用说明) +[![Platform: Windows + macOS](https://img.shields.io/badge/Platform-Windows%20%2B%20macOS-0078D6.svg)](#使用说明) [主文档](README.md) | **简体中文** | [English](README.en.md) -AndroidTreeView 是一个用于 Android 设备巡检、测试与管理的 Windows 桌面工具。主程序负责设备总览、详情、投屏、基础工具和设置；Mini 版本保持独立运行，常驻监听设备并自动投屏。 +AndroidTreeView 是一个用于 Android 设备巡检、测试与管理的桌面工具，支持 Windows 与 macOS（Apple Silicon）。主程序负责设备总览、详情、投屏、基础工具和设置；Mini 版本保持独立运行，常驻监听设备并自动投屏。 -当前版本：**v1.0.5**。 +当前版本：**v1.0.6**。 ## 产品样式展示 -![AndroidTreeView 设备总览](docs/images/product-devices-v1.0.5.png) +![AndroidTreeView 设备总览](docs/images/product-devices-v1.0.6.png) ## 功能 @@ -36,13 +36,21 @@ dotnet run --project src/AndroidTreeView.App dotnet run --project src/AndroidTreeView.Mini ``` -## Windows 使用说明 +功能规划与实施文档入口见 [docs/roadmap-features.md](docs/roadmap-features.md)。 + +## 使用说明 1. 安装 Android platform-tools，或让应用在启动时引导选择 `adb.exe`。 2. 在手机上开启开发者选项和 USB 调试。 3. 连接手机并允许 USB 调试授权。 4. 主程序会显示设备卡片；Mini 会自动监听并启动投屏。 +### macOS 说明 + +- 从 Release 下载 `AndroidTreeView-<版本>-osx-arm64.zip`，解压后将 `AndroidTreeView.app` 拖入 `/Applications`。 +- 首次打开若被 Gatekeeper 拦截，右键「打开」，或执行 `xattr -dr com.apple.quarantine AndroidTreeView.app` 放行。 +- 设备卡片的「CLI 终端」在 macOS 上通过 Terminal.app 打开，编号菜单与 Windows 一致。 + ADB 安装与排错见 [docs/adb-requirements.md](docs/adb-requirements.md)。 ## 自动更新 @@ -61,13 +69,13 @@ ADB 安装与排错见 [docs/adb-requirements.md](docs/adb-requirements.md)。 ./packaging/build-update-zip.ps1 -Product Mini -Rid win-x64 ``` -默认产物版本是 `1.0.5`。只发布 x64 架构。验证输出包含主程序和 Mini 的上传 ZIP，例如： +默认产物版本是 `1.0.6`。只发布 x64 架构。验证输出包含主程序和 Mini 的上传 ZIP，例如： ```text -artifacts/AndroidTreeView-1.0.5-win-x64.zip -artifacts/AndroidTreeView-1.0.5-osx-arm64.zip -artifacts/AndroidTreeView-Mini-1.0.5-win-x64.zip -artifacts/AndroidTreeView-Mini-1.0.5-osx-arm64.zip +artifacts/AndroidTreeView-1.0.6-win-x64.zip +artifacts/AndroidTreeView-1.0.6-osx-arm64.zip +artifacts/AndroidTreeView-Mini-1.0.6-win-x64.zip +artifacts/AndroidTreeView-Mini-1.0.6-osx-arm64.zip ``` 更多细节见 [docs/packaging.md](docs/packaging.md)。 diff --git a/README.en.md b/README.en.md index 3865168..f665102 100644 --- a/README.en.md +++ b/README.en.md @@ -9,11 +9,11 @@ AndroidTreeView is a desktop tool for inspecting, testing, and managing Android devices through ADB. The full app shows device cards, detail pages, mirroring, tools, settings, and updates. The Mini app stays resident, watches for devices, and starts mirroring automatically after authorization. -Current version: **v1.0.5**. Current verification target: solution build passes, all tests pass, and GitHub Actions creates Windows x64 and macOS Apple Silicon ZIP artifacts for both App and Mini. +Current version: **v1.0.6**. Current verification target: solution build passes, all tests pass, and GitHub Actions creates Windows x64 and macOS Apple Silicon ZIP artifacts for both App and Mini. ## Product Preview -![AndroidTreeView device overview](docs/images/product-devices-v1.0.5.png) +![AndroidTreeView device overview](docs/images/product-devices-v1.0.6.png) ## Features @@ -58,6 +58,8 @@ dotnet run --project src/AndroidTreeView.App dotnet run --project src/AndroidTreeView.Mini ``` +See [docs/roadmap-features.md](docs/roadmap-features.md) for feature roadmaps and implementation plans. + If ADB is not found, the app opens an ADB setup screen. Install Android platform-tools and add it to `PATH`, or choose `adb.exe` manually. ## Enable USB Debugging @@ -78,7 +80,7 @@ See [docs/adb-requirements.md](docs/adb-requirements.md) for platform-tools setu ## Release ZIP Packaging -The product version is currently `1.0.5` and is kept in sync across runtime version, App/Mini assembly metadata, manifest, and the ZIP build script. Official releases are produced only by the GitHub Actions `Publish` workflow. +The product version is currently `1.0.6` and is kept in sync across runtime version, App/Mini assembly metadata, manifest, and the ZIP build script. Official releases are produced only by the GitHub Actions `Publish` workflow. Local commands are for packaging validation only: @@ -90,10 +92,10 @@ Local commands are for packaging validation only: Example output: ```text -artifacts/AndroidTreeView-1.0.5-win-x64.zip -artifacts/AndroidTreeView-1.0.5-osx-arm64.zip -artifacts/AndroidTreeView-Mini-1.0.5-win-x64.zip -artifacts/AndroidTreeView-Mini-1.0.5-osx-arm64.zip +artifacts/AndroidTreeView-1.0.6-win-x64.zip +artifacts/AndroidTreeView-1.0.6-osx-arm64.zip +artifacts/AndroidTreeView-Mini-1.0.6-win-x64.zip +artifacts/AndroidTreeView-Mini-1.0.6-osx-arm64.zip ``` ## Auto Update diff --git a/README.md b/README.md index 441c240..676fcee 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,17 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-0E7A5F.svg)](LICENSE) [![.NET 10](https://img.shields.io/badge/.NET-10.0-512BD4.svg)](https://dotnet.microsoft.com/) [![Avalonia 11.3](https://img.shields.io/badge/Avalonia-11.3-663399.svg)](https://avaloniaui.net/) -[![Platform: Windows](https://img.shields.io/badge/Platform-Windows-0078D6.svg)](#windows-使用说明) +[![Platform: Windows + macOS](https://img.shields.io/badge/Platform-Windows%20%2B%20macOS-0078D6.svg)](#使用说明) **简体中文** | [English](README.en.md) | [中文副本](README-CN.md) -AndroidTreeView 是一个用于 Android 设备巡检、测试与管理的 Windows 桌面工具。主程序负责设备总览、详情、投屏、基础工具、设置和更新；Mini 版本保持独立运行，常驻监听设备，并在授权后自动启动投屏。 +AndroidTreeView 是一个用于 Android 设备巡检、测试与管理的桌面工具，支持 Windows 与 macOS（Apple Silicon）。主程序负责设备总览、详情、投屏、基础工具、设置和更新；Mini 版本保持独立运行，常驻监听设备，并在授权后自动启动投屏。 -当前版本：**v1.0.5**。当前验证目标：App 构建通过、Mini 构建通过、全量测试通过，打包链路能为 App 和 Mini 分别生成 x64 上传 ZIP。 +当前版本：**v1.0.6**。当前验证目标：App 构建通过、Mini 构建通过、全量测试通过，打包链路能为 App 和 Mini 分别生成 x64 上传 ZIP。 ## 产品样式展示 -![AndroidTreeView 设备总览](docs/images/product-devices-v1.0.5.png) +![AndroidTreeView 设备总览](docs/images/product-devices-v1.0.6.png) ## 核心能力 @@ -38,6 +38,7 @@ src/ AndroidTreeView.Shared AndroidTreeView.App AndroidTreeView.Mini + AndroidTreeView.Mini.Mac tests/ AndroidTreeView.*.Tests packaging/ @@ -58,6 +59,8 @@ dotnet run --project src/AndroidTreeView.App dotnet run --project src/AndroidTreeView.Mini ``` +功能规划与实施文档入口见 [docs/roadmap-features.md](docs/roadmap-features.md)。 + 如果找不到 ADB，主程序会显示 ADB 设置页。请安装 Android platform-tools 并加入 `PATH`，或手动选择 `adb.exe`。 ## 开启 USB 调试 @@ -69,16 +72,22 @@ dotnet run --project src/AndroidTreeView.Mini ADB 安装和排错见 [docs/adb-requirements.md](docs/adb-requirements.md)。 -## Windows 使用说明 +## 使用说明 1. 启动 AndroidTreeView。 2. 连接已开启并授权 USB 调试的 Android 设备。 3. 使用设备卡片查看状态、投屏、打开 CLI 或执行非破坏性工具。 4. 通过设置或关于页检查并安装更新。 +### macOS 说明 + +- 从 Release 下载 `AndroidTreeView-<版本>-osx-arm64.zip`，解压后将 `AndroidTreeView.app` 拖入 `/Applications`。 +- 首次打开若被 Gatekeeper 拦截（未签名），右键选择「打开」，或执行 `xattr -dr com.apple.quarantine AndroidTreeView.app` 放行。 +- 设备卡片的「CLI 终端」在 macOS 上通过 Terminal.app 打开，提供与 Windows 一致的编号菜单（设备信息 / adb shell / logcat / 重启 / 关机 等）。 + ## Release ZIP 打包 -当前版本号统一为 `1.0.5`，运行时版本、App/Mini 程序集版本、manifest 和 `build-update-zip.ps1` 默认版本保持一致。正式发布只通过 GitHub Actions 的 `Publish` 工作流完成，发布只接受 x64。 +当前版本号统一为 `1.0.6`，运行时版本、App/Mini 程序集版本、manifest 和 `build-update-zip.ps1` 默认版本保持一致。正式发布只通过 GitHub Actions 的 `Publish` 工作流完成，发布只接受 x64。 本地命令仅用于验证打包链路： @@ -90,10 +99,10 @@ ADB 安装和排错见 [docs/adb-requirements.md](docs/adb-requirements.md)。 示例输出： ```text -artifacts/AndroidTreeView-1.0.5-win-x64.zip -artifacts/AndroidTreeView-1.0.5-osx-arm64.zip -artifacts/AndroidTreeView-Mini-1.0.5-win-x64.zip -artifacts/AndroidTreeView-Mini-1.0.5-osx-arm64.zip +artifacts/AndroidTreeView-1.0.6-win-x64.zip +artifacts/AndroidTreeView-1.0.6-osx-arm64.zip +artifacts/AndroidTreeView-Mini-1.0.6-win-x64.zip +artifacts/AndroidTreeView-Mini-1.0.6-osx-arm64.zip ``` ## 自动更新 diff --git a/docs/app-contract.md b/docs/app-contract.md index 5e79538..0f9d351 100644 --- a/docs/app-contract.md +++ b/docs/app-contract.md @@ -2,7 +2,7 @@ This document records the App-layer contract for the full app and the Mini companion. -Current product version: `1.0.5`. +Current product version: `1.0.6`. ## Shared Services diff --git a/docs/packaging.md b/docs/packaging.md index 3cc2a6d..2c2d9f0 100644 --- a/docs/packaging.md +++ b/docs/packaging.md @@ -2,7 +2,7 @@ Packaging files live under `packaging/`. -Current default product version: `1.0.5`. +Current default product version: `1.0.6`. Official release artifacts are created by GitHub Actions (`.github/workflows/publish.yml`) only. Local packaging commands are validation helpers and must not be used as the authority for publishing a release. @@ -11,14 +11,14 @@ Official release artifacts are created by GitHub Actions (`.github/workflows/pub Every GitHub Release must contain exactly these four ZIP packages plus matching `.sha256` sidecars: ```text -artifacts/AndroidTreeView-1.0.5-win-x64.zip -artifacts/AndroidTreeView-1.0.5-win-x64.zip.sha256 -artifacts/AndroidTreeView-1.0.5-osx-arm64.zip -artifacts/AndroidTreeView-1.0.5-osx-arm64.zip.sha256 -artifacts/AndroidTreeView-Mini-1.0.5-win-x64.zip -artifacts/AndroidTreeView-Mini-1.0.5-win-x64.zip.sha256 -artifacts/AndroidTreeView-Mini-1.0.5-osx-arm64.zip -artifacts/AndroidTreeView-Mini-1.0.5-osx-arm64.zip.sha256 +artifacts/AndroidTreeView-1.0.6-win-x64.zip +artifacts/AndroidTreeView-1.0.6-win-x64.zip.sha256 +artifacts/AndroidTreeView-1.0.6-osx-arm64.zip +artifacts/AndroidTreeView-1.0.6-osx-arm64.zip.sha256 +artifacts/AndroidTreeView-Mini-1.0.6-win-x64.zip +artifacts/AndroidTreeView-Mini-1.0.6-win-x64.zip.sha256 +artifacts/AndroidTreeView-Mini-1.0.6-osx-arm64.zip +artifacts/AndroidTreeView-Mini-1.0.6-osx-arm64.zip.sha256 ``` Windows ZIPs contain the published application files, the platform-matched `scrcpy` bundle, and `release.json` at the ZIP root. macOS ZIPs contain a top-level `.app` bundle (`AndroidTreeView.app` or `AndroidTreeView Mini.app`); the published files, `scrcpy`, and `release.json` live inside the bundle. @@ -74,7 +74,7 @@ The updater uses `release.json` to distinguish an automated release ZIP from a r "product": "App", "productName": "AndroidTreeView", "appKey": "android-tree-view-app", - "version": "1.0.5", + "version": "1.0.6", "platform": "win", "arch": "x64", "rid": "win-x64", @@ -102,8 +102,8 @@ The WiX project rejects non-x64 platforms. `build-update-zip.ps1` writes checksums automatically. Manual verification: ```powershell -Get-FileHash -Algorithm SHA256 artifacts\AndroidTreeView-1.0.5-win-x64.zip -Get-FileHash -Algorithm SHA256 artifacts\AndroidTreeView-Mini-1.0.5-win-x64.zip +Get-FileHash -Algorithm SHA256 artifacts\AndroidTreeView-1.0.6-win-x64.zip +Get-FileHash -Algorithm SHA256 artifacts\AndroidTreeView-Mini-1.0.6-win-x64.zip ``` The sidecar uses ` *` format for compatibility with `sha256sum -c`. diff --git a/docs/publishing.md b/docs/publishing.md index 63585c5..cbe0b4f 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -2,7 +2,7 @@ Repository: `Birditch/AndroidTreeView`. -Current product version: `1.0.5`. +Current product version: `1.0.6`. ## Release Policy @@ -37,24 +37,24 @@ Keep these values identical for every release: - `src/AndroidTreeView.App/app.manifest` -> `assemblyIdentity version` - `packaging/build-update-zip.ps1` -> default `Version` -For `1.0.5`, release artifacts are named: +For `1.0.6`, release artifacts are named: ```text -AndroidTreeView-1.0.5-win-x64.zip -AndroidTreeView-1.0.5-win-x64.zip.sha256 -AndroidTreeView-1.0.5-osx-arm64.zip -AndroidTreeView-1.0.5-osx-arm64.zip.sha256 -AndroidTreeView-Mini-1.0.5-win-x64.zip -AndroidTreeView-Mini-1.0.5-win-x64.zip.sha256 -AndroidTreeView-Mini-1.0.5-osx-arm64.zip -AndroidTreeView-Mini-1.0.5-osx-arm64.zip.sha256 +AndroidTreeView-1.0.6-win-x64.zip +AndroidTreeView-1.0.6-win-x64.zip.sha256 +AndroidTreeView-1.0.6-osx-arm64.zip +AndroidTreeView-1.0.6-osx-arm64.zip.sha256 +AndroidTreeView-Mini-1.0.6-win-x64.zip +AndroidTreeView-Mini-1.0.6-win-x64.zip.sha256 +AndroidTreeView-Mini-1.0.6-osx-arm64.zip +AndroidTreeView-Mini-1.0.6-osx-arm64.zip.sha256 ``` ## Build Upload ZIP Packages Official publication happens through the `Publish` GitHub Actions workflow: -- push a tag named `v..`, for example `v1.0.5` +- push a tag named `v..`, for example `v1.0.6` - or run `workflow_dispatch` and provide the same version string The workflow validates on Windows, verifies the pinned scrcpy release against the latest upstream release, builds the two Windows portable ZIPs and two macOS `.app` bundle ZIPs, writes SHA-256 sidecars, uploads workflow artifacts, and creates the GitHub Release. @@ -77,8 +77,8 @@ The full app and Mini share the same update implementation but use different app The Windows update channel must point each product key at its own Windows ZIP: -- `android-tree-view-app` -> `AndroidTreeView-1.0.5-win-x64.zip` -- `android-tree-view-mini` -> `AndroidTreeView-Mini-1.0.5-win-x64.zip` +- `android-tree-view-app` -> `AndroidTreeView-1.0.6-win-x64.zip` +- `android-tree-view-mini` -> `AndroidTreeView-Mini-1.0.6-win-x64.zip` `NekoIndexUpdateService` queries the configured internal update API and compares the returned version with `AppInfo.Version`. `UpdateInstaller` downloads the package, verifies SHA-256 metadata when present, extracts the ZIP, verifies the portable Windows x64 manifest, and starts the automated update script. @@ -97,7 +97,7 @@ Minimum response contract: "data": { "appKey": "android-tree-view-app", "title": "AndroidTreeView", - "version": "1.0.5", + "version": "1.0.6", "zip": { "sha256": "<64-character sha256>", "downloadUrl": "/api/resources/android-tree-view-app/versions/latest/archive" @@ -114,11 +114,11 @@ Minimum response contract: Use this flow for the intranet update server: -1. Push a `v1.0.5` tag or run the `Publish` GitHub Actions workflow manually. +1. Push a `v1.0.6` tag or run the `Publish` GitHub Actions workflow manually. 2. Download the GitHub Actions-built Windows ZIP and `.sha256` sidecar for each Windows update channel. 3. Upload the ZIPs to the internal server storage. -4. Configure `/api/update/android-tree-view-app/latest` to return `AndroidTreeView-1.0.5-win-x64.zip` metadata. -5. Configure `/api/update/android-tree-view-mini/latest` to return `AndroidTreeView-Mini-1.0.5-win-x64.zip` metadata. +4. Configure `/api/update/android-tree-view-app/latest` to return `AndroidTreeView-1.0.6-win-x64.zip` metadata. +5. Configure `/api/update/android-tree-view-mini/latest` to return `AndroidTreeView-Mini-1.0.6-win-x64.zip` metadata. 6. Confirm the `sha256` value matches the uploaded ZIP. 7. Use the app "Check for updates" action to test download, validation, replacement, cleanup, and restart. diff --git a/docs/requirements-v1.md b/docs/requirements-v1.md index bf4147f..179ee4a 100644 --- a/docs/requirements-v1.md +++ b/docs/requirements-v1.md @@ -1,6 +1,6 @@ # AndroidTreeView Requirements Addendum -Current product version: `1.0.5`. +Current product version: `1.0.6`. This addendum extends `docs/architecture.md` and reflects the current App + Mini direction. diff --git a/docs/roadmap-features.md b/docs/roadmap-features.md index 4e50d1b..23a631c 100644 --- a/docs/roadmap-features.md +++ b/docs/roadmap-features.md @@ -16,6 +16,14 @@ This roadmap captures the current App + Mini direction after the shared service ## Remaining Backlog +### Semi-Automatic Root Wizard + +- Design: [`superpowers/specs/2026-07-09-semi-auto-root-design.md`](superpowers/specs/2026-07-09-semi-auto-root-design.md) +- Implementation plan: [`superpowers/plans/2026-07-10-semi-auto-root-implementation.md`](superpowers/plans/2026-07-10-semi-auto-root-implementation.md) +- Complete the M0 real-device Magisk patching spike before implementing the flashing workflow. +- Keep all boot writes inside the guided flow with explicit confirmation, an original-image backup, + unambiguous fastboot device matching, and per-slot failure reporting. + ### Device Actions - Keep right-click/card actions universal, non-destructive by default, and no-root-required unless a root-only action is explicitly marked. diff --git a/docs/superpowers/plans/2026-07-10-semi-auto-root-implementation.md b/docs/superpowers/plans/2026-07-10-semi-auto-root-implementation.md new file mode 100644 index 0000000..8aa411c --- /dev/null +++ b/docs/superpowers/plans/2026-07-10-semi-auto-root-implementation.md @@ -0,0 +1,356 @@ +# 半自动 Root 功能实施计划 + +- 日期：2026-07-10 +- 状态：草案，等待实施 +- 设计依据：[`../specs/2026-07-09-semi-auto-root-design.md`](../specs/2026-07-09-semi-auto-root-design.md) +- 目标平台：`win-x64`、`osx-arm64` + +## 1. 交付目标 + +在完整 App 中增加可恢复、可取消、带两次风险确认的 Root 向导。用户选择与当前设备匹配的 +刷机包后，App 提取原始 `boot.img`、备份、用固定版本 Magisk 修补、检测 fastboot 解锁与槽位， +最后在明确确认后刷入并重启。 + +Mini、Mini.Mac 不提供 Root 向导，也不携带 Magisk 或 payload-dumper。 + +## 2. 仓库现状与计划校正 + +实施时以当前代码为准，不能照设计稿重复建设已经存在的能力： + +- `IFastbootService`、`FastbootService`、fastboot 设备合并和卡片展示已经存在。 +- `build/AndroidTreeView.Scrcpy.targets` 与 `packaging/build-update-zip.ps1` 已把 fastboot 放在 + App 的 `scrcpy/` 目录，Windows 与 macOS App 包均可携带 fastboot。 +- 完整 App 已是 `net10.0 + Avalonia`，`osx-arm64` 发布链路已经存在，不需要新建 macOS App。 +- 现有 `FastbootService` 面向设备列表，普通失败会被吞掉；Root 写入链路必须返回可诊断的严格结果。 +- 现有 `ProcessRunner` 是静态内部类，无法直接用假对象覆盖 payload-dumper 和 fastboot 错误路径。 +- 当前通用 `IDialogService` 不支持“阅读风险并勾选确认”，第二确认点应由 Root 页面状态门控。 + +## 3. 不可跳过的技术门槛 + +### M0：验证 Magisk 修补链路 + +这是主实现的前置门槛。Magisk `v30.7` APK 中存在 `assets/boot_patch.sh`、 +`assets/util_functions.sh` 和各 ABI 的 `libmagisk*.so`，但 `boot_patch.sh` 明确要求脚本、 +`magiskboot`、`magiskinit`、`magisk`、`init-ld` 与 `stub.apk` 位于同一目录。安装 APK 并不等于 +这些文件可被普通 `adb shell` 直接访问。 + +验证步骤： + +1. 使用一台可丢弃数据、bootloader 已解锁的测试机和与该机版本匹配的原始 `boot.img`。 +2. 执行 `adb install -r Magisk-v30.7.apk`，记录 package path、ABI 与 shell 可访问的组件路径。 +3. 尝试在非 root 的 `adb shell` 中调用已安装 App 的修补组件，产出 `new-boot.img`。 +4. pull 修补结果并让 Magisk App/`magiskboot` 验证镜像；只有验证通过才进入 Task 1。 + +通过标准：不依赖设备已 root，命令可重复执行，修补产物非空，清理后无残留临时文件。 + +失败处理：暂停主实现，更新设计规格并让用户选择“从已校验 APK 提取官方组件后 push”或其他 +方案。不得在未确认的情况下悄悄换成第三方桌面 `magiskboot`。 + +### M1：首次真实刷写 + +只在单元测试、包验证和 M0 全部通过后执行。先用非 A/B 测试机或可恢复设备验证单槽写入，再验证 +A/B 双槽及第二槽失败提示。真实刷写不放入 CI。 + +## 4. 依赖顺序 + +```text +M0 Magisk 实机验证 + -> Task 1 可替换的外部命令执行层 + -> Task 2 领域模型与 Core 合约 + -> Task 3 ZIP / 嵌套 ZIP 提取 + -> Task 4 Root 工具固定版本与打包 + -> Task 5 payload.bin 提取 + -> Task 6 原始 boot 备份 + -> Task 7 Magisk 修补服务 + -> Task 8 严格 fastboot 检测与刷写 + -> Task 9 向导状态机 + -> Task 10 App 页面、导航、本地化 + -> Task 11 集成与回归测试 + -> Task 12 发布包验证、文档和 M1 +``` + +## 5. 分步实施 + +### Task 1：建立可替换的外部命令执行层 + +文件： + +- 新增 `src/AndroidTreeView.Core/Interfaces/IExternalCommandRunner.cs` +- 新增 `src/AndroidTreeView.Core/Services/ExternalCommandRequest.cs` +- 新增 `src/AndroidTreeView.Core/Services/ExternalCommandResult.cs` +- 新增 `src/AndroidTreeView.Adb/Services/ExternalCommandRunner.cs` +- 修改 `src/AndroidTreeView.Adb/Services/FastbootService.cs` +- 修改 `src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/TestDoubles/FakeExternalCommandRunner.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Services/FastbootServiceTests.cs` + +步骤： + +1. 先写失败测试，覆盖 fastboot 缺失、超时、非零退出、stderr 输出和取消传播。 +2. 用 `ExternalCommandRunner` 适配现有 `ProcessRunner.RunAsync`，保留参数列表传递，禁止拼 shell 字符串。 +3. 让 `FastbootService` 注入 runner；设备列表相关 API 继续保持 best-effort 行为。 +4. 在 Shared 中用 `TryAddSingleton` 注册 runner，不改 Mini 的现有行为。 + +验收：`dotnet test tests/AndroidTreeView.Adb.Tests --filter FullyQualifiedName~FastbootServiceTests` + +### Task 2：定义 Root 领域模型与 Core 合约 + +文件： + +- 新增 `src/AndroidTreeView.Models/Rooting/BootImageSource.cs` +- 新增 `src/AndroidTreeView.Models/Rooting/BootImageInfo.cs` +- 新增 `src/AndroidTreeView.Models/Rooting/RootWizardState.cs` +- 新增 `src/AndroidTreeView.Models/Rooting/RootWizardSnapshot.cs` +- 新增 `src/AndroidTreeView.Models/Rooting/FastbootBootLayout.cs` +- 新增 `src/AndroidTreeView.Models/Rooting/FirmwarePackageMetadata.cs` +- 新增 `src/AndroidTreeView.Models/Rooting/RootErrorCode.cs` +- 新增 `src/AndroidTreeView.Core/Interfaces/IBootImageExtractor.cs` +- 新增 `src/AndroidTreeView.Core/Interfaces/IBootBackupService.cs` +- 新增 `src/AndroidTreeView.Core/Interfaces/IMagiskPatcher.cs` +- 新增 `src/AndroidTreeView.Core/Interfaces/IRootWizardService.cs` +- 新增 `src/AndroidTreeView.Core/Exceptions/RootWorkflowException.cs` + +约束： + +- `RootWizardSnapshot` 保存设备 serial、包路径、工作目录、原始/修补镜像、备份路径、槽位和错误码。 +- 错误对 UI 暴露稳定错误码，不直接把任意 stderr 当成用户文案。 +- 状态增加 `BlockedAmbiguousFastboot`：ADB 重启后若出现多个 fastboot 设备且无法唯一匹配，禁止刷写。 +- 所有 I/O 接口均为 async，并传递 `CancellationToken`。 + +验收：Core 和 Models 无上层项目引用，`dotnet build AndroidTreeView.sln -p:EnableWindowsTargeting=true`。 + +### Task 3：实现安全的 ZIP 与 Pixel 嵌套 ZIP 提取 + +文件： + +- 新增 `src/AndroidTreeView.Adb/Parsers/PackageTypeDetector.cs` +- 新增 `src/AndroidTreeView.Adb/Parsers/FirmwarePackageMetadataParser.cs` +- 新增 `src/AndroidTreeView.Adb/Services/BootImageExtractor.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Parsers/PackageTypeDetectorTests.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Parsers/FirmwarePackageMetadataParserTests.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Services/BootImageExtractorTests.cs` + +测试先覆盖：顶层 `boot.img`、大小写差异、Pixel `image-*.zip`、payload、无目标文件、重复目标、 +损坏 ZIP、路径穿越、取消和工作目录清理。 + +实现约束： + +- 只允许一层嵌套 ZIP；条目路径必须经过 `Path.GetFullPath` 边界检查。 +- 不把整个大包读入内存；使用流复制。 +- 设定单条目和总展开大小上限，拒绝 ZIP bomb。 +- 读取 OTA `META-INF/com/android/metadata` 与 Pixel `android-info.txt`；元数据明确不匹配当前 + `ro.product.device`/product 时硬阻止，元数据缺失时标记为“无法自动验证”并留给第二确认点。 +- 每次会话使用独立的 `root-work//`，失败时清理，成功时由向导结束后清理。 + +验收：提取测试全部通过，且测试用临时目录在成功、失败、取消后均被回收。 + +### Task 4：固定并打包 Root 工具 + +固定版本： + +- Magisk：`v30.7`，资产 `Magisk-v30.7.apk`，SHA-256 + `e0d32d2123532860f97123d927b1bb86c4e08e6fd8a48bfc6b5bee0afae9ebd5`。 +- payload-dumper-go：`1.3.0`，使用上游 `payload-dumper-go_sha256checksums.txt` 中的 + `windows_amd64` 与 `darwin_arm64` 校验值。 +- fastboot：继续复用现有 App `scrcpy/fastboot[.exe]`，不新增第二份 platform-tools。 + +文件： + +- 新增 `build/AndroidTreeView.RootTools.targets` +- 修改 `src/AndroidTreeView.App/AndroidTreeView.App.csproj` +- 修改 `packaging/build-update-zip.ps1` +- 修改 `.github/workflows/publish.yml` +- 新增 `tools/verify-roottools-latest.ps1` + +步骤： + +1. App 单独导入 RootTools target；Mini 和 Mini.Mac 不导入。 +2. 下载后先计算 SHA-256，不匹配立即失败，再解包或复制。 +3. 输出布局固定为 `root-tools/magisk/Magisk-v30.7.apk` 和 + `root-tools/payload-dumper/payload-dumper-go[.exe]`。 +4. macOS 包为 payload-dumper 设置执行位。 +5. 发布工作流验证 App 包含三个 Root 必需工具，Mini 包不包含 `root-tools/`。 + +验收：对 `win-x64` 与 `osx-arm64` 各运行一次 App 打包，并检查 ZIP 条目和哈希失败路径。 + +### Task 5：接入 payload.bin 提取 + +文件： + +- 修改 `src/AndroidTreeView.Adb/Services/BootImageExtractor.cs` +- 新增 `src/AndroidTreeView.Adb/Services/RootToolPaths.cs` +- 扩展 `tests/AndroidTreeView.Adb.Tests/Services/BootImageExtractorTests.cs` + +步骤： + +1. 用 fake runner 写测试，固定断言可执行文件、argv、超时和输出目录。 +2. 对裸 payload 与 ZIP 内 payload 使用同一分支，只请求 `boot` 分区。 +3. runner 非零退出、超时或未产出 `boot.img` 时抛稳定错误码。 +4. 校验输出文件存在、大小合理，再返回 `BootImageInfo`。 + +验收：不安装真实 payload-dumper 也能覆盖所有流程分支；打包 smoke test 再验证真实二进制可启动。 + +### Task 6：实现原始 boot 备份 + +文件： + +- 新增 `src/AndroidTreeView.Infrastructure/Rooting/BootBackupService.cs` +- 新增 `tests/AndroidTreeView.Infrastructure.Tests/BootBackupServiceTests.cs` +- 修改 `src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs` + +约束： + +- 目录为 `~/.androidtreeview/root-backups/`。 +- serial 先清洗为文件名安全字符；使用 UTC 时间和随机后缀防碰撞。 +- 先写临时文件，再原子移动；取消或复制失败不得留下半个备份。 +- 返回绝对路径，并验证备份长度与源文件相同。 + +验收：覆盖非法 serial、同秒多次备份、取消、源文件不存在和成功内容一致。 + +### Task 7：实现 Magisk 修补服务 + +文件： + +- 新增 `src/AndroidTreeView.Adb/Parsers/CpuAbiParser.cs` +- 新增 `src/AndroidTreeView.Adb/Services/MagiskPatcher.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Parsers/CpuAbiParserTests.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Services/MagiskPatcherTests.cs` +- 修改 `src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs` + +严格按 M0 验证通过的命令序列实现：安装固定 APK、探测 ABI、创建会话临时目录、push 镜像、执行 +官方修补脚本、pull 结果、校验产物，并在 `finally` 中清理手机临时目录。 + +测试覆盖：安装失败、未知 ABI、push 失败、脚本失败、pull 失败、空产物、取消和清理失败不遮蔽主错误。 +日志不得输出完整敏感 stderr；UI 只接收错误码与经过裁剪的诊断摘要。 + +验收：`MagiskPatcherTests` 全部通过，随后在 M0 测试机重复一次端到端修补。 + +### Task 8：增加严格 fastboot 检测与刷写结果 + +文件： + +- 新增 `src/AndroidTreeView.Adb/Commands/FastbootArgs.cs` +- 新增 `src/AndroidTreeView.Adb/Parsers/FastbootVarParser.cs` +- 修改 `src/AndroidTreeView.Core/Interfaces/IFastbootService.cs` +- 修改 `src/AndroidTreeView.Adb/Services/FastbootService.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Commands/FastbootArgsTests.cs` +- 新增 `tests/AndroidTreeView.Adb.Tests/Parsers/FastbootVarParserTests.cs` +- 扩展 `tests/AndroidTreeView.Adb.Tests/Services/FastbootServiceTests.cs` + +新增能力：等待指定/唯一 fastboot 设备、读取 `unlocked`、`slot-count`、`has-slot:boot` 与 +`current-slot`、单槽刷 `boot`、A/B 依次刷 `boot_a` 和 `boot_b`、返回失败分区和 stderr 摘要、 +重启系统。 + +安全规则： + +- fastboot 设备无法唯一识别时返回 `AmbiguousDevice`，绝不选择列表第一台。 +- 可执行文件先查已定位 adb 的同目录，再回退到 App 自带 `scrcpy/fastboot[.exe]`。 +- `unlocked` 不是明确 yes/true 时按未解锁处理。 +- `has-slot:boot=no` 才判为非 A/B；`has-slot:boot=yes` 且槽位数明确时判为 A/B；信息矛盾或 + 缺失时不猜布局，进入阻塞状态。 +- A/B 的 `boot_a` 成功、`boot_b` 失败时返回部分写入结果，UI 必须显示设备处于危险中间态。 +- 非零退出和超时不得继续执行下一条写命令。 + +验收：argv、stdout/stderr 解析和全部失败分支均由纯单测固定。 + +### Task 9：实现可恢复的 Root 向导状态机 + +文件： + +- 新增 `src/AndroidTreeView.Core/Services/RootWizardService.cs` +- 新增 `tests/AndroidTreeView.Core.Tests/RootWizardServiceTests.cs` +- 修改 `src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs` + +状态转换由显式方法驱动：`SelectPackage`、`ExtractAndPatchAsync`、`ConfirmBootloaderAsync`、 +`DetectFastbootAsync`、`ConfirmFlashAsync`、`RetryAsync`、`CancelAsync`。服务不弹 UI，也不自行越过 +确认点。 + +测试固定以下不变量： + +- 未完成备份不能进入 flash 确认。 +- 包元数据明确与设备不匹配时不能进入修补或 flash；无法验证时必须显示额外风险提示。 +- 未解锁、槽位未知、设备歧义、未勾选风险确认均不能调用 flash。 +- 取消会杀掉当前外部进程并保留原始备份。 +- 重试只重跑失败步骤，不重复刷已成功的分区。 +- 完成/中止后清理工作目录，但永不删除备份。 + +验收：状态转换表的每条边和每个阻塞状态至少有一个测试。 + +### Task 10：接入 App 导航、页面和本地化 + +文件： + +- 新增 `src/AndroidTreeView.App/ViewModels/RootWizardViewModel.cs` +- 新增 `src/AndroidTreeView.App/Views/RootWizardView.axaml` +- 新增 `src/AndroidTreeView.App/Views/RootWizardView.axaml.cs` +- 修改 `src/AndroidTreeView.App/ViewModels/AppEnums.cs` +- 修改 `src/AndroidTreeView.App/ViewModels/MainWindowViewModel.cs` +- 修改 `src/AndroidTreeView.App/Views/MainWindow.axaml` +- 修改 `src/AndroidTreeView.App/AppServices.cs` +- 修改 `src/AndroidTreeView.App/Services/IFilePickerService.cs` +- 修改 `src/AndroidTreeView.App/Services/FilePickerService.cs` +- 修改两个 `Strings*.resx` + +实现： + +- Root VM 注册为 singleton，使用户切换导航后不丢工作流。 +- 文件选择器新增单选刷机包入口，只接受 ZIP 与 payload；给 `FilePickerService` 注入 + `ILocalizationService`，选择器标题与文件类型名称也必须本地化。 +- 第一次确认可用现有 `IDialogService`；第二次在 Root 页面显示备份路径、目标分区和风险复选框。 +- 第二确认点同时显示设备代号、包元数据匹配结果；无法自动验证时使用独立醒目警告。 +- `FlashCommand` 的 CanExecute 同时依赖状态和 `HasAcknowledgedRisk`。 +- 页面只绑定 VM，使用 `x:DataType`；所有正常错误映射成 `root.error.*`。 +- 狭窄窗口下步骤条可横向滚动，底部操作区不遮挡错误和日志。 + +验收：两个 ResX 键集合完全一致，App headless boot 能解析 Root 页面全部 compiled bindings。 + +### Task 11：补齐 App 集成和回归测试 + +文件： + +- 新增 `tests/AndroidTreeView.App.Tests/RootWizardViewModelTests.cs` +- 修改 `tests/AndroidTreeView.App.Tests/Fakes.cs` +- 修改 `tests/AndroidTreeView.App.Tests/ServiceGraphTests.cs` +- 修改 `tests/AndroidTreeView.App.Tests/BootSmokeTests.cs` + +覆盖：导航、选包取消、两个确认门、锁定设备、设备歧义、A/B 警告、第二槽失败、重试、取消、语言切换、 +DI 图和 XAML 启动。再运行全量 build/test/format，确认设备列表与现有 best-effort fastboot 行为未回归。 + +验收命令： + +```bash +dotnet restore AndroidTreeView.sln -p:EnableWindowsTargeting=true +dotnet build AndroidTreeView.sln -c Release --no-restore -p:EnableWindowsTargeting=true +dotnet test AndroidTreeView.sln -c Release --no-build -p:EnableWindowsTargeting=true +dotnet format AndroidTreeView.sln --verify-no-changes +``` + +### Task 12：发布验证、文档同步和 M1 + +修改：`CLAUDE.md`、`AGENTS.md`、`docs/architecture.md`、`docs/app-contract.md`、 +`docs/packaging.md`、`docs/publishing.md`、`docs/roadmap-features.md` 和统一版本位置。 + +发布前： + +1. 生成 App 的 `win-x64` 与 `osx-arm64` ZIP，确认 fastboot、Magisk APK、payload-dumper 和执行位。 +2. 生成两个 Mini ZIP，确认没有 `root-tools/`，体积与依赖没有意外增长。 +3. 在干净 Windows 与 macOS 机器启动 App，完成选包、提取和到达第一次确认点的无写入 smoke test。 +4. 按 M1 在可恢复真机执行刷写；记录设备、包版本、槽位、命令结果和回滚方式。 +5. M1 通过后再 bump 版本、更新 changelog 并进入发布流程。 + +## 6. 完成定义 + +- M0、M1 有可复核记录，且没有未说明的手工步骤。 +- 两个平台可从发布 ZIP 启动并走完整向导。 +- 未解锁、设备歧义、槽位未知、包不匹配、包损坏、工具缺失和命令失败都无法越过写入门。 +- 原始 boot 在任何刷写前已完成本地备份，失败或取消不会删除。 +- App 不因正常设备/命令错误崩溃；错误均有中英文文案和可操作的下一步。 +- 全量测试通过，两个 ResX 键集合一致，Mini 不携带 Root 工具。 + +## 7. 明确不在本计划内 + +- 自动解锁 bootloader。 +- 刷写 `boot` 以外分区。 +- 自动回刷、卸载 Root 或救砖向导。 +- 厂商私有包与动态分区拆包。 +- Linux 发布包或 macOS x64 发布包。 diff --git a/docs/superpowers/specs/2026-07-09-semi-auto-root-design.md b/docs/superpowers/specs/2026-07-09-semi-auto-root-design.md new file mode 100644 index 0000000..bea6286 --- /dev/null +++ b/docs/superpowers/specs/2026-07-09-semi-auto-root-design.md @@ -0,0 +1,315 @@ +# 半自动 Root 功能 — 设计规格 + +- 日期：2026-07-09 +- 状态：设计已确认，实施计划已起草；Magisk 修补链路待 M0 实机验证 +- 关联记忆：`root-feature-relaxes-safety` +- 实施计划：[`../plans/2026-07-10-semi-auto-root-implementation.md`](../plans/2026-07-10-semi-auto-root-implementation.md) + +> 仓库现状校正（2026-07-10）：当前代码已包含 `IFastbootService` / `FastbootService`、fastboot +> 设备列表合并、Windows/macOS App 打包和 App 内 fastboot 分发。实施时扩展这些现有能力， +> 不再新建第二套 fastboot locator/environment 或 platform-tools 目录。Magisk“安装 APK 后直接 +> 调用组件”仍是 M0 硬门槛，未通过前不得进入刷写主链路。 + +## 1. 目标与范围 + +为 AndroidTreeView 增加一个**半自动 Root 功能**：用户手动上传刷机包，工具自动提取 +`boot.img`、用官方 Magisk 组件修补、引导进入 bootloader、把修补后的 `boot.img` 刷入设备。 +以**分步向导**形态交付，写操作前强制确认，刷入前自动备份原始 `boot.img`。 + +### 1.1 第一版明确要做 + +- 上传刷机包（本地文件选择）。 +- 提取 `boot.img`： + - zip 内含裸 `boot.img`（含 Pixel factory 的嵌套 `image-*.zip`）。 + - `payload.bin`（A/B OTA），通过打包的 `payload_dumper` 解出。 +- Magisk 修补：工具**构建时打包固定版本官方 Magisk APK**（SHA-256 校验），运行时 + `adb install` 到手机，调用**已装 Magisk App 自带的** `boot_patch.sh` + native 组件在手机端 + 完成修补，pull 回修补后镜像。 +- 写操作链路：`adb push` → `adb reboot bootloader` → **flash boot（A/B 机型两个槽都刷）** → + `fastboot reboot`。 + - **非 A/B 机型**：`fastboot flash boot `。 + - **A/B 机型**：`fastboot flash boot_a ` **且** `fastboot flash boot_b ` + （两槽都刷入同一修补后镜像，避免槽位翻转/刷错槽导致 Magisk 不生效）。 + - 刷入前**强制提示用户**双槽都会被写入及其风险（见 §5.3 确认 2、§3 已知风险）。 +- 只读检测：`fastboot getvar unlocked`（解锁状态）、**A/B 布局探测 + （联合 `slot-count`、`has-slot:boot`、`current-slot`，矛盾或缺失时阻止刷写）**、设备 ABI 探测。 +- **刷入前自动备份原始未修补 `boot.img`** 到本地用户目录。 +- 平台：**Windows + macOS 双平台**，共用同一套 MVVM 代码。 + +### 1.2 第一版明确不做（后续再议） + +- `fastboot flashing unlock`（解锁 bootloader，会抹数据）——**仅检测状态 + 文字引导，不代执行**。 +- 刷其他分区（system / vbmeta / recovery / super 等）。 +- 卸载 root / 一键恢复原厂 boot（仅提供备份文件与引导，不做自动回刷向导）。 +- 厂商私有包格式（`.ozip`、动态分区 super.img 拆分等）。 + +## 2. 方向性决策（已与用户确认） + +| 决策 | 选择 | 理由 | +|---|---|---| +| 与"只读/安全"定位冲突 | **放宽定位**，接受工具含刷机写操作 | 用户明确要 fastboot 刷入的半自动 root | +| 支持平台 | **Windows + macOS 双平台** | 两平台都要能真正刷机 | +| Magisk 修补执行位置 | **手机端执行官方 magiskboot/组件** | 官方 Android 二进制天然可跑，比桌面第三方二进制可靠 | +| Magisk 组件获取 | **构建时打包固定版 Magisk APK，运行时 `adb install`，用已装 App 自带组件修补** | APK 内即含各 ABI native 组件；装 App 后 `boot_patch.sh` 环境完整，比裸跑 `/data/local/tmp` 坑少 | +| 自动化程度 | **分步向导 + 写操作前强制确认** | 变砖风险高，不做无人值守一键刷 | +| 包格式范围 | **zip(含 Pixel 嵌套) + payload.bin** | 覆盖 factory image 与现代 A/B OTA | +| A/B 机型刷入策略 | **两个槽 `boot_a`/`boot_b` 都刷同一镜像 + 刷入前强制提示** | 免探测 active slot、免刷错槽；代价（跨版本双槽变砖）以提示告知用户承担 | +| 工具打包 | **构建时按平台下载打包进 `tools/`** | 对齐现有 scrcpy/adb 打包，开箱即用 | +| UI 落点 | **App 新导航页，复用现有 Windows/macOS App 发布链路** | 双平台共用同一套 Avalonia MVVM 代码 | +| 修补第 4 步实现 | **安装官方 Magisk APK 后跑其自带 `boot_patch.sh`** | 最贴近官方；实机验证列为高风险里程碑 | + +## 3. 可行性结论 + +核心链路技术上全部可实现，跨平台可行。真正的风险**不在技术**，而在三个工具无法根除、 +必须由用户承担的前提： + +- **前提 1 — bootloader 已解锁**：未解锁则 `fastboot flash` 必然失败。工具只检测并引导， + 不自动解锁（解锁抹数据、需在手机上按键、部分厂商需解锁码）。 +- **前提 2 — 包与设备匹配**：刷错版本/架构可能变砖。工具做基本校验与警告，但无法保证包正确。 +- **前提 3 — A/B 双槽刷入的跨版本风险（已知、以提示承担）**：A/B 机型两个槽都刷入同一 + 修补后镜像。若两个槽当前系统版本不一致（如 OTA 后未满一个周期），把当前版本的 boot 刷进 + 另一槽会造成 boot 与该槽 system/vendor 版本错配，**日后回滚到该槽可能 bootloop**（延迟变砖， + 刷入当下无异常）。工具**无法可靠检测两槽版本**，故在**确认 2 强制提示**用户此风险，由用户 + 在知情后承担（对应 §2 决策：省掉刷错槽 → 接受此代价）。 + +设计上以**分步向导 + 强制确认 + 自动备份原始 boot** 将风险降到可控。 + +**最高技术不确定性**：Magisk 修补的第 4 步（执行 `boot_patch.sh`）不是单条命令。现方案先 +`adb install` 官方 Magisk APK，再调用其自带的 `boot_patch.sh` + native 组件——装 App 后 +`boot_patch.sh` 环境（`MAGISKBIN`/APK 资源）更完整，比裸跑 `/data/local/tmp` 可靠，但 +**"已装 App 的 `boot_patch.sh` 能否被 `adb shell` 直接调到"仍需实机验证**（assets 内脚本安装后 +不一定落在可直接执行位置，可能仍需从 APK 提取），**必须实机验证**（见 §8 里程碑）。 + +## 4. 分层与工程落点 + +严格遵循项目分层（下层不引用上层）： + +``` +Models FlashPackage, BootImageInfo(Path, Source, OriginalPackageName), + RootWizardState(enum), DeviceFastbootStatus, PackageType(enum) + ↑ +Core 接口：IBootImageExtractor, IMagiskPatcher, IFastbootService, IRootWizardService + IExternalCommandRunner、RootException 类型 + ↑ +Adb / Infrastructure + Adb：扩展现有 FastbootService、 + BootImageExtractor(zip + payload.bin)、MagiskPatcher(install APK + 手机端执行)、 + Parsers：FastbootVarParser、PackageTypeDetector、CpuAbiParser + Infra：BootBackupService（备份原始 boot 到用户目录） + ↑ +Shared AddAndroidTreeViewSharedServices() 内 TryAdd 注册全部新服务 + ↑ +App RootWizardViewModel + RootWizardView（新导航页，分步向导） +``` + +- 所有 fastboot/adb 写操作走 `ProcessRunner`（异步、可取消、杀进程树）。 +- 解析类为纯函数放 `AndroidTreeView.Adb.Parsers`，配套解析测试（项目硬规则）。 +- fastboot 复用 App 已有 `scrcpy/fastboot[.exe]`；Magisk APK 与 payload-dumper 通过新建 + `build/AndroidTreeView.RootTools.targets` 按发布 RID 下载、校验并只打包进完整 App。 + +## 5. 向导状态机与流程 + +### 5.1 状态枚举 `RootWizardState` + +``` +Idle 初始 +PackageSelected 已选刷机包 +Extracting 提取 boot.img 中（自动） +BootExtracted 已提取（含来源：PlainZip / NestedZip / Payload） +Patching 修补中（adb install Magisk APK → 手机执行 boot_patch.sh → pull 回） +BootPatched 已得修补后 boot + 已本地备份原始 boot +AwaitingBootloaderConfirm ⛔ 强制确认点 1：即将重启进 bootloader +RebootingToBootloader adb reboot bootloader（自动） +InFastboot 已进 fastboot，检测解锁状态 + A/B 布局（多变量联合判定） +Blocked_Locked 未解锁：引导用户，终止自动流程（可重新检测） +AwaitingFlashConfirm ⛔ 强制确认点 2：即将 flash boot（显示目标槽位；A/B 明确告知双槽都刷） +Flashing fastboot flash boot（A/B：先 boot_a 再 boot_b，自动） +Rebooting fastboot reboot（自动） +Completed 完成 +Failed 任一步失败（带错误信息 + 重试当前步 / 中止） +``` + +### 5.2 Happy Path 时序 + +``` +选包 → [自动]提取 → [自动]修补+备份 → ⛔确认1 → [自动]进bootloader + → 检测解锁 → ⛔确认2 → [自动]flash → [自动]reboot → 完成 +``` + +### 5.3 两个强制确认点 + +1. **确认 1（进 bootloader 前）**：提示手机将重启进 fastboot、保持数据线稳定。 +2. **确认 2（flash 前）**：显示目标分区 `boot`、修补后镜像、**原始 boot 备份路径**、 + **目标槽位（A/B 机型明确显示"将同时刷入 boot_a 和 boot_b"）**、红色"刷错可能变砖"警告； + **A/B 机型额外红字提示**：两个槽都会被写入同一镜像，若两槽系统版本不一致，日后回滚到另一槽 + 可能变砖（§3 前提 3）；用户勾选"我已了解风险"后方可点"刷入"。 + +### 5.4 关键分支 + +- **Blocked_Locked（未解锁）**：向导停止，显示解锁引导（开发者选项 OEM 解锁、 + `fastboot flashing unlock` 会抹数据、部分厂商需解锁码）。**工具不代执行解锁**。 + 用户自行解锁后可"重新检测"继续。 +- **Failed（任一步失败）**：显示该步 stderr/错误摘要（映射成友好文案），提供"重试当前步"或 + "中止"。中止不留危险中间态（若已在 fastboot，引导用户 `fastboot reboot` 回系统）。 +- **可取消**：每个自动步走 `CancellationToken`，用户可随时取消（取消后进入 Failed/可重试）。 + +## 6. 核心机制 + +### 6.1 boot.img 提取（`BootImageExtractor`） + +输入包文件，按类型分派，输出 `boot.img` 本地路径 + 来源标记 +（`BootImageInfo { Path, Source, OriginalPackageName }`）。 + +**包类型判定**（纯函数 `PackageTypeDetector`，读文件头/枚举 zip 条目）： + +- zip 顶层有 `boot.img` → **PlainZip** +- zip 含 `image-*.zip`（Pixel factory）→ **NestedZip**（解一层内层 zip 再取 `boot.img`） +- zip 含 `payload.bin` → **Payload** +- 裸 `payload.bin` 文件 → **Payload** +- 都不匹配 → 抛 `RootException`，友好提示"未在包内找到 boot.img" + +**提取**： + +- PlainZip / NestedZip → 纯 C# `System.IO.Compression`，无外部依赖。 +- Payload → 调用打包的 `payload_dumper`（走 `ProcessRunner`）解出 `boot` 分区。 +- 输出到工作区 `~/.androidtreeview/root-work//`。 + +**可测试性**：`PackageTypeDetector` 纯函数（zip 条目列表/文件头样本做测试）；payload 解包用假 +`ProcessRunner` 测试流程/错误。 + +### 6.2 Magisk 修补（`MagiskPatcher`，安装官方 APK 后手机端执行） + +前提：设备已连接、adb 已授权（复用现有 `DeviceMonitor` / 设备状态）。 + +1. **安装 Magisk App**（`EnsureMagiskInstalledAsync`）：`adb install -r tools/magisk/Magisk.apk` + （`-r` 覆盖重装，兼容用户已装旧版）。APK 内即含各 ABI native 组件（`lib//lib*.so`）。 + 装 App **不设新强制确认点**，仅在步骤条/日志告知"正在安装 Magisk App"（loc key + `root.step.install_magisk`）。install 失败进 `Failed`。 +2. **探测 ABI**：`adb shell getprop ro.product.cpu.abi`（纯函数 `CpuAbiParser`），用于定位已装 + Magisk App 的 native 组件路径（`lib/`）。 +3. **本地备份原始 boot.img**（`BootBackupService`）：复制到 + `~/.androidtreeview/root-backups/--boot-original.img`，路径供确认 2 显示。 +4. **修补**：push 待修补 `boot.img` 到手机临时目录 `/data/local/tmp/atv_root/`，`adb shell` 调用 + **已装 Magisk App 自带的** `boot_patch.sh`（其可自解析 `MAGISKBIN`/APK 资源，内部调用 + `magiskboot unpack/cpio/repack` + `magiskinit`/`magisk`），产出 `new-boot.img`。 +5. **pull 回**：`adb pull .../new-boot.img /boot-patched.img`。 +6. **清理**手机临时目录。 + +> ⚠️ 第 4 步为最高技术不确定性环节：装 App 后 `boot_patch.sh` 环境更完整，但**"已装 App 的 +> `boot_patch.sh` 能否被 `adb shell` 直接调到"仍未完全消除不确定性**（APK 内 `assets` 脚本安装后 +> 不一定落在可直接执行位置，可能仍需从 APK 提取脚本再 push），需实机验证（见 §8）。 + +### 6.3 fastboot 服务（`FastbootService`，走 `ProcessRunner`，全部 async + CancellationToken） + +| 方法 | 命令 | 说明 | +|---|---|---| +| `RebootToBootloaderAsync` | `adb reboot bootloader` | 从系统进 fastboot | +| `WaitForFastbootDeviceAsync` | `fastboot devices` 轮询 | 等设备在 fastboot 出现（带超时） | +| `GetUnlockStatusAsync` | `fastboot getvar unlocked` | 只读，`FastbootVarParser` 解析 `unlocked: yes/no` | +| `GetBootLayoutAsync` | `fastboot getvar slot-count` + `has-slot:boot` + `current-slot` | 只读；联合判定 A/B，信息矛盾或缺失时返回 Unknown | +| `FlashBootAsync` | 非 A/B：`fastboot flash boot `；A/B：`fastboot flash boot_a ` **且** `fastboot flash boot_b ` | 核心写操作；A/B 两槽都刷同一镜像 | +| `RebootAsync` | `fastboot reboot` | 刷完回系统 | + +解析 `getvar` / `fastboot devices` 输出为纯函数 + 解析测试。`slot-count`、`has-slot:boot`、 +`current-slot` 复用同一 `FastbootVarParser`。A/B 双槽刷入时，`boot_a` 成功、`boot_b` 失败要 +视为整体失败（进 `Failed`，错误摘要注明哪个槽失败），不可停在"只刷了一个槽"的中间态。 + +### 6.4 fastboot 定位（复用现有 `FastbootService`） + +现有 `FastbootService.ExecutablePath` 从 `IAdbEnvironment` 已定位的 adb 同目录解析 +`fastboot[.exe]`；发布脚本也已把 fastboot 放入 App 的 `scrcpy/` 目录。Root 向导扩展该服务的 +严格检测/刷写结果，不新建第二套 locator/environment。缺失时向导显示“未找到 fastboot”，不崩溃。 + +### 6.5 备份服务（`BootBackupService`，Infrastructure 层） + +- 修补前把原始 boot.img 存到 `~/.androidtreeview/root-backups/`，文件名含序列号 + 时间戳。 +- 提供"列出/打开备份目录"给 UI，便于变砖时找回。 + +## 7. 工具打包 — `build/AndroidTreeView.RootTools.targets` + +仿 `AndroidTreeView.Scrcpy.targets`，构建/发布时按平台下载并打包： + +``` +tools/ + scrcpy/ 现有目录，已含 adb + fastboot + root-tools/ + payload-dumper/ win-x64 / osx-arm64 对应 payload-dumper-go + magisk/ + Magisk.apk 固定版本官方 APK，运行时 adb install +``` + +- Root 工具只打包进完整 App；Mini / Mini.Mac 不携带。 +- 下载源写明 URL + SHA-256 校验，文档登记版本，对齐项目"下载工具需校验 SHA-256"风格： + - fastboot：复用现有 Google platform-tools 下载与 App 打包路径。 + - magisk：官方 Magisk GitHub release 的 APK 整包（不在桌面侧拆 native 二进制，组件随 App + 安装到手机后使用）。 + - payload_dumper：可信开源发布。 +- 新增 `tools/verify-roottools-latest.ps1`（仿 `verify-scrcpy-latest.ps1`）检查上游新版本。 + +## 8. 高风险里程碑（实机验证） + +以下无法单测，须实机验证并在开发中预留调整轮次： + +1. **`boot_patch.sh` 修补链路** — `adb install` 官方 Magisk APK 后，能调用其自带 + `boot_patch.sh` 在真机产出可用 `new-boot.img`（重点验证已装 App 的脚本是否可被 `adb shell` + 直接调到）。 +2. **真实 flash** — `fastboot flash boot` 在已解锁真机上成功且能正常开机。 +3. **payload.bin 解包** — `payload_dumper` 在 `win-x64`、`osx-arm64` 均能正确解出 boot 分区。 +4. **跨平台 fastboot/adb** — Windows x64 与 macOS arm64 下二进制均能定位与执行。 + +## 9. App UI + +- 新导航页，命名遵循 ViewLocator 约定（`RootWizardViewModel` → `RootWizardView`），严格 MVVM + （`[ObservableProperty]` / `[RelayCommand]`），编译绑定 `x:DataType`。 +- 侧栏新增导航项（新 loc key `nav.root`）。页面：顶部步骤条反映 `RootWizardState`，中间当前步 + 内容/进度/日志，底部操作按钮（下一步/确认/取消/重试）。 +- 两个强制确认为醒目对话框 + 复选框（未勾选"我已了解风险"则"刷入"禁用）。 +- flash 步骤用红色警告样式，与只读功能区分。 +- `RootWizardViewModel` 仅编排 `IRootWizardService`，负责状态→UI 映射、UI 线程 marshal + （`Dispatcher.UIThread.Post`）、错误映射成友好 `ErrorMessage`（App 永不因正常错误崩溃）。 +- macOS 支持：让 App 能在 macOS 构建/运行，Root 页双平台共用同一 MVVM 代码。 + +## 10. 本地化 + +- 所有向导文案、按钮、警告、错误映射、引导说明新增 key 到**两个 ResX 都加** + （`Strings.resx` 英文 + `Strings.zh-Hans.resx` 中文），键集保持一致。 +- 命名示例：`root.wizard.title`、`root.step.extract`、`root.step.install_magisk`（安装 Magisk + App 步骤/日志文案）、`root.confirm.flash.warning`、 + `root.confirm.flash.ab.dualslot`（双槽刷入提示）、`root.confirm.flash.targetslot`（目标槽位显示）、 + `root.blocked.locked.guide`、`root.error.*`（含 `root.error.install.magisk`：装 APK 失败； + `root.error.flash.slotb`：第二槽刷入失败）。 +- XAML 用 `{loc:Localize Key=...}`，VM 用 `_localization.Get/Format`。 + +## 11. 测试 + +- **Adb.Tests** 新增： + - `Parsers/FastbootVarParserTests`（`unlocked` / `slot-count` / `has-slot:boot` / + `current-slot` / `fastboot devices`） + - `Parsers/PackageTypeDetectorTests`（zip 条目 → 包类型） + - `Parsers/CpuAbiParserTests`（`ro.product.cpu.abi` 解析） + - `Commands/`：fastboot/adb argv 构建测试（含 A/B 双槽 `flash boot_a`/`boot_b` 的 argv） + - `Services/`：`BootImageExtractor`、`MagiskPatcher`、`FastbootService`（假 + `IExternalCommandRunner`， + 覆盖流程与错误路径；`MagiskPatcher` 覆盖 `adb install` 成功→调 `boot_patch.sh`、install + 失败→`Failed`、ABI 探测；`FlashBootAsync` 覆盖非 A/B 单槽、A/B 双槽成功、A/B 第二槽失败→整体失败） +- **App.Tests** 新增：`RootWizardViewModel` 状态机推进、确认门控（未勾选不能 flash）、错误映射、 + 未解锁→Blocked 分支；DI 图解析新服务（`ServiceGraphTests`）。 +- **实机验证**（§8）：无法单测，作为手动验证清单。 + +## 12. CLAUDE.md 更新 + +因放宽只读定位，实现时需： + +- 修改"Read-only / safe by design"条目：说明工具现含**受控、需多重确认的刷机写操作**（仅 + Root 向导内 boot 刷入链路），其余功能仍保持只读；解锁 bootloader 仍不自动执行。 +- Architecture / Bundled tools 段补充 fastboot、magisk 组件、payload_dumper 打包说明。 +- 版本按发布规则统一 bump。 + +## 13. 明确的非目标（YAGNI） + +- 不做 bootloader 自动解锁。 +- 不做 boot 以外分区刷写。 +- 不做一键恢复/卸载 root 向导（仅备份 + 引导）。 +- 不支持厂商私有包格式。 +- 不引入桌面版第三方 `magiskboot`（改用安装官方 Magisk APK 后调用其自带组件，不在桌面侧拆 + native 二进制）。 diff --git a/packaging/AndroidTreeView.Package.wixproj b/packaging/AndroidTreeView.Package.wixproj index bcf193e..27147e4 100644 --- a/packaging/AndroidTreeView.Package.wixproj +++ b/packaging/AndroidTreeView.Package.wixproj @@ -9,7 +9,7 @@ app and then invokes this project with the right properties, e.g.: dotnet build packaging/AndroidTreeView.Package.wixproj -c Release ^ - -p:Platform=x64 -p:ProductVersion=1.0.5 -p:SelfContained=false ^ + -p:Platform=x64 -p:ProductVersion=1.0.6 -p:SelfContained=false ^ -p:PublishDir= Requires the WiX v5 SDK, restored automatically from nuget.org via the Sdk attribute. @@ -23,7 +23,7 @@ - 1.0.5 + 1.0.6 AndroidTreeView AndroidTreeView.App.exe {6C0B8E2A-4F1D-4B7C-9A3E-2D5F8B1C0E4A} @@ -41,7 +41,7 @@ harvest. build-msi.ps1 sets this; the default is only for manual runs. --> $(MSBuildThisFileDirectory)..\artifacts\publish\$(Platform)\ - + $(ProductArtifactName)-$(ProductVersion)-$(Platform) Package false diff --git a/packaging/Bundle.wxs b/packaging/Bundle.wxs index 45dd3b6..e305dad 100644 --- a/packaging/Bundle.wxs +++ b/packaging/Bundle.wxs @@ -8,13 +8,13 @@ Build after the MSI has been produced: wix build packaging/Bundle.wxs -arch x64 ^ - -d ProductVersion=1.0.5 ^ + -d ProductVersion=1.0.6 ^ -d Platform=x64 ^ - -d MsiPath=artifacts\AndroidTreeView-1.0.5-x64.msi ^ + -d MsiPath=artifacts\AndroidTreeView-1.0.6-x64.msi ^ -d DotNetRuntimeExe=C:\path\windowsdesktop-runtime-10.0.x-win-x64.exe ^ -ext WixToolset.BootstrapperApplications.wixext ^ -ext WixToolset.Netfx.wixext ^ - -o artifacts\AndroidTreeView-1.0.5-x64-setup.exe + -o artifacts\AndroidTreeView-1.0.6-x64-setup.exe --> - + diff --git a/packaging/build-msi.ps1 b/packaging/build-msi.ps1 index d40e71c..3266be6 100644 --- a/packaging/build-msi.ps1 +++ b/packaging/build-msi.ps1 @@ -27,7 +27,7 @@ Build configuration. Default: Release. .PARAMETER Version - Product version. Default: 1.0.5. Must match AndroidTreeView.Core.AppInfo.Version. + Product version. Default: 1.0.6. Must match AndroidTreeView.Core.AppInfo.Version. .EXAMPLE ./build-msi.ps1 -Product App -Arch x64 @@ -49,7 +49,7 @@ param( [string]$Configuration = 'Release', - [string]$Version = '1.0.5' + [string]$Version = '1.0.6' ) $ErrorActionPreference = 'Stop' diff --git a/packaging/build-update-zip.ps1 b/packaging/build-update-zip.ps1 index fa688df..ba1b4ed 100644 --- a/packaging/build-update-zip.ps1 +++ b/packaging/build-update-zip.ps1 @@ -27,7 +27,7 @@ param( [string]$Configuration = 'Release', - [string]$Version = '1.0.5' + [string]$Version = '1.0.6' ) $ErrorActionPreference = 'Stop' @@ -250,6 +250,70 @@ function ConvertTo-PlistString { return [System.Security.SecurityElement]::Escape($Value) } +function New-IcnsFromPng { + param( + [Parameter(Mandatory = $true)] + [string]$SourcePng, + + [Parameter(Mandatory = $true)] + [string]$OutputIcns + ) + + # macOS .app icons are .icns files; the repo only ships a 256x256 PNG, so build the .icns from it + # with the system tools (sips resizes each slot, iconutil packs the iconset). Requires macOS. + if (-not (Get-Command sips -ErrorAction SilentlyContinue) -or -not (Get-Command iconutil -ErrorAction SilentlyContinue)) { + Write-Warning 'sips/iconutil not found; skipping macOS app icon generation.' + return $false + } + + $iconsetDir = "$OutputIcns.iconset" + if (Test-Path -LiteralPath $iconsetDir) { + Remove-Item -Recurse -Force -LiteralPath $iconsetDir + } + New-Item -ItemType Directory -Force -Path $iconsetDir | Out-Null + + # name => pixel size for the standard iconset slots (1x + @2x). macOS app artwork occupies + # about 81% of each icon canvas; the transparent safe area keeps it aligned with system icons. + $slots = [ordered]@{ + 'icon_16x16.png' = 16 + 'icon_16x16@2x.png' = 32 + 'icon_32x32.png' = 32 + 'icon_32x32@2x.png' = 64 + 'icon_128x128.png' = 128 + 'icon_128x128@2x.png' = 256 + 'icon_256x256.png' = 256 + 'icon_256x256@2x.png' = 512 + 'icon_512x512.png' = 512 + 'icon_512x512@2x.png' = 1024 + } + + foreach ($entry in $slots.GetEnumerator()) { + $target = Join-Path $iconsetDir $entry.Key + $contentSize = [Math]::Max(1, [Math]::Round($entry.Value * 0.8125)) + $resizedTarget = "$target.resized.png" + + & sips -z $contentSize $contentSize $SourcePng --out $resizedTarget *> $null + if ($LASTEXITCODE -ne 0) { + throw "sips failed to resize '$($entry.Key)' from '$SourcePng'." + } + + & sips -p $entry.Value $entry.Value $resizedTarget --out $target *> $null + if ($LASTEXITCODE -ne 0) { + throw "sips failed to add the macOS safe area to '$($entry.Key)'." + } + + Remove-Item -Force -LiteralPath $resizedTarget + } + + & iconutil -c icns $iconsetDir -o $OutputIcns + if ($LASTEXITCODE -ne 0) { + throw "iconutil failed to build '$OutputIcns'." + } + + Remove-Item -Recurse -Force -LiteralPath $iconsetDir + return $true +} + function New-MacOSAppBundle { param( [Parameter(Mandatory = $true)] @@ -306,6 +370,25 @@ function New-MacOSAppBundle { $bundleIdentifier = "com.birditch.$($ProductConfig.AppKey.Replace('-', '.'))" $displayName = $ProductConfig.ProductName $executableName = $ProductConfig.Executable + + # Build the app icon (.icns) from the App's PNG so the bundle shows in Dock/Finder. + $iconSourcePng = Join-Path $repoRoot 'src/AndroidTreeView.App/Assets/atv-icon.png' + $iconFileName = '' + if (Test-Path -LiteralPath $iconSourcePng) { + $icnsPath = Join-Path $resourcesDir 'AppIcon.icns' + if (New-IcnsFromPng -SourcePng $iconSourcePng -OutputIcns $icnsPath) { + $iconFileName = 'AppIcon' + } + } else { + Write-Warning "Icon source '$iconSourcePng' not found; bundle will have no icon." + } + + $iconPlistEntry = if ($iconFileName) { + " CFBundleIconFile`n $(ConvertTo-PlistString $iconFileName)`n" + } else { + '' + } + $infoPlist = @" @@ -317,7 +400,7 @@ function New-MacOSAppBundle { $(ConvertTo-PlistString $displayName) CFBundleExecutable $(ConvertTo-PlistString $executableName) - CFBundleIdentifier +$iconPlistEntry CFBundleIdentifier $(ConvertTo-PlistString $bundleIdentifier) CFBundleInfoDictionaryVersion 6.0 @@ -342,6 +425,23 @@ function New-MacOSAppBundle { Set-ExecutableBits -RidInfo $RidInfo -Directory $macOSDir -Names @($ProductConfig.Executable) Set-ExecutableBits -RidInfo $RidInfo -Directory (Join-Path $macOSDir 'scrcpy') -Names @('scrcpy', 'adb', 'fastboot') + if (-not (Get-Command codesign -ErrorAction SilentlyContinue)) { + throw 'codesign is required to produce a valid macOS app bundle.' + } + + # dotnet signs the apphost before it is wrapped in the final bundle. Sign again after adding + # Info.plist and Resources so the bundle resource envelope matches the shipped contents. + # New-PackageArchive uses ditto to preserve the extended-attribute signatures on managed DLLs. + & codesign --force --deep --sign - --timestamp=none $bundleRoot + if ($LASTEXITCODE -ne 0) { + throw "codesign failed for '$bundleRoot'." + } + + & codesign --verify --deep --strict $bundleRoot + if ($LASTEXITCODE -ne 0) { + throw "codesign verification failed for '$bundleRoot'." + } + return $BundleStageDir } @@ -456,16 +556,18 @@ function New-PackageArchive { } if ($RidInfo.IsMacOS) { - $zipFullPath = [System.IO.Path]::GetFullPath($ZipPath) - Push-Location $SourceDir - try { - & zip -qry $zipFullPath . - if ($LASTEXITCODE -ne 0) { - throw "zip failed with exit code $LASTEXITCODE." - } + if (-not (Get-Command ditto -ErrorAction SilentlyContinue)) { + throw 'ditto is required to preserve macOS app bundle signatures in ZIP packages.' + } + + $appBundles = @(Get-ChildItem -LiteralPath $SourceDir -Directory -Filter '*.app') + if ($appBundles.Count -ne 1) { + throw "Expected exactly one .app bundle under '$SourceDir', found $($appBundles.Count)." } - finally { - Pop-Location + + & ditto -c -k --sequesterRsrc --keepParent $appBundles[0].FullName $ZipPath + if ($LASTEXITCODE -ne 0) { + throw "ditto failed with exit code $LASTEXITCODE." } return @@ -491,6 +593,10 @@ $zipPath = Join-Path $artifacts "$baseName.zip" $zipChecksumPath = "$zipPath.sha256" $packageKind = if ($ridInfo.IsWindows) { 'portable-x64' } else { "portable-$($ridInfo.Rid)" } $bundleFastbootValue = if ($productConfig.BundleFastboot) { 'true' } else { 'false' } +# macOS has no system-level "install .NET runtime" prompt like Windows, so a framework-dependent +# .app silently fails to launch on machines without the runtime. Bundle the runtime into the macOS +# .app (self-contained). Windows stays framework-dependent: its apphost shows the OS download prompt. +$selfContainedValue = if ($ridInfo.IsMacOS) { 'true' } else { 'false' } New-Item -ItemType Directory -Force -Path $artifacts | Out-Null Assert-UnderDirectory -Path $publishDir -Parent $artifacts @@ -513,7 +619,7 @@ $publishArgs = @( $productConfig.Project, '--configuration', $Configuration, '--runtime', $ridInfo.Rid, - '--self-contained', 'false', + '--self-contained', $selfContainedValue, "-p:Version=$Version", "-p:AssemblyVersion=$Version.0", "-p:FileVersion=$Version.0", diff --git a/src/AndroidTreeView.App/AndroidTreeView.App.csproj b/src/AndroidTreeView.App/AndroidTreeView.App.csproj index 94aded3..de7dc78 100644 --- a/src/AndroidTreeView.App/AndroidTreeView.App.csproj +++ b/src/AndroidTreeView.App/AndroidTreeView.App.csproj @@ -8,10 +8,10 @@ Assets/atv-icon.ico true true - 1.0.5 - 1.0.5.0 - 1.0.5.0 - 1.0.5 + 1.0.6 + 1.0.6.0 + 1.0.6.0 + 1.0.6 false diff --git a/src/AndroidTreeView.App/Resources/Strings.resx b/src/AndroidTreeView.App/Resources/Strings.resx index ff3f94f..d6b9297 100644 --- a/src/AndroidTreeView.App/Resources/Strings.resx +++ b/src/AndroidTreeView.App/Resources/Strings.resx @@ -171,6 +171,12 @@ CLI Terminal + + The CLI terminal is not supported on this operating system. + + + Failed to open the CLI terminal. + Details @@ -655,7 +661,7 @@ Could not start the update process - Ready to check the internal update channel + Ready to check GitHub Releases Update Source @@ -664,13 +670,13 @@ Package Key - No build has been uploaded for this channel yet + No GitHub Release has been published yet - Could not reach the internal update server + Could not reach GitHub Releases - The update server rejected the request + GitHub rejected the update request The update metadata is incomplete @@ -709,4 +715,3 @@ Failed to load {0} - diff --git a/src/AndroidTreeView.App/Resources/Strings.zh-Hans.resx b/src/AndroidTreeView.App/Resources/Strings.zh-Hans.resx index 830a777..0276d87 100644 --- a/src/AndroidTreeView.App/Resources/Strings.zh-Hans.resx +++ b/src/AndroidTreeView.App/Resources/Strings.zh-Hans.resx @@ -171,6 +171,12 @@ CLI 终端 + + 当前操作系统不支持 CLI 终端。 + + + 打开 CLI 终端失败。 + 详情 @@ -655,7 +661,7 @@ 无法启动更新流程 - 可以检查内网更新通道 + 可以检查 GitHub Releases 更新源 @@ -664,13 +670,13 @@ 包标识 - 这个通道还没有上传版本 + GitHub 仓库还没有发布版本 - 无法连接内网更新服务 + 无法连接 GitHub Releases - 更新服务拒绝了本次请求 + GitHub 拒绝了本次更新请求 更新信息不完整 @@ -709,4 +715,3 @@ 加载 {0} 失败 - diff --git a/src/AndroidTreeView.App/Services/CliLauncher.cs b/src/AndroidTreeView.App/Services/CliLauncher.cs index 552c5ba..feb6e58 100644 --- a/src/AndroidTreeView.App/Services/CliLauncher.cs +++ b/src/AndroidTreeView.App/Services/CliLauncher.cs @@ -27,13 +27,15 @@ public interface ICliLauncher public sealed class CliLauncher : ICliLauncher { private readonly IAdbEnvironment _environment; + private readonly ILocalizationService _localization; private readonly ILogger _logger; private readonly List _processes = new(); private readonly object _gate = new(); - public CliLauncher(IAdbEnvironment environment, ILogger logger) + public CliLauncher(IAdbEnvironment environment, ILocalizationService localization, ILogger logger) { _environment = environment; + _localization = localization; _logger = logger; } @@ -42,29 +44,83 @@ public void Open(string serial, string title, bool fastboot) try { var toolsDir = ResolveToolsDir() ?? AppContext.BaseDirectory; - var script = fastboot ? BuildFastbootMenu(serial, toolsDir) : BuildAdbMenu(serial, toolsDir); - var safe = new string(serial.Where(char.IsLetterOrDigit).ToArray()); - var batPath = Path.Combine(Path.GetTempPath(), $"atv-cli-{(safe.Length == 0 ? "device" : safe)}.bat"); - File.WriteAllText(batPath, script); - - var psi = new ProcessStartInfo + if (safe.Length == 0) { - FileName = "cmd.exe", - Arguments = $"/K \"{batPath}\"", - WorkingDirectory = toolsDir, - UseShellExecute = true, // reliably opens a visible console window from a GUI process - }; + safe = "device"; + } - var process = Process.Start(psi); - if (process is not null) + if (OperatingSystem.IsWindows()) + { + OpenWindows(serial, safe, toolsDir, fastboot); + } + else if (OperatingSystem.IsMacOS()) + { + OpenMac(serial, safe, toolsDir, fastboot); + } + else { - Track(process); + Notifier.Notify(_localization.Get("cli.unsupported"), NotifierLevel.Warning); } } catch (Exception ex) { _logger.LogWarning(ex, "Failed to open CLI terminal for {Serial}.", serial); + Notifier.Notify(_localization.Get("cli.launchFailed"), NotifierLevel.Error); + } + } + + // Windows: write a menu .bat and open it in a cmd.exe /K console. + private void OpenWindows(string serial, string safe, string toolsDir, bool fastboot) + { + var script = fastboot ? BuildFastbootMenu(serial, toolsDir) : BuildAdbMenu(serial, toolsDir); + var batPath = Path.Combine(Path.GetTempPath(), $"atv-cli-{safe}.bat"); + File.WriteAllText(batPath, script); + + var psi = new ProcessStartInfo + { + FileName = "cmd.exe", + Arguments = $"/K \"{batPath}\"", + WorkingDirectory = toolsDir, + UseShellExecute = true, // reliably opens a visible console window from a GUI process + }; + + var process = Process.Start(psi); + if (process is not null) + { + Track(process); + } + } + + // macOS: write an equivalent .command shell script and open it in Terminal.app. + // Note: `open` returns immediately and the Terminal window is an independent process, so + // ShutdownAll() cannot close it — that's intentional; we don't force-close a user's terminal. + [System.Runtime.Versioning.SupportedOSPlatform("macos")] + private void OpenMac(string serial, string safe, string toolsDir, bool fastboot) + { + var script = fastboot ? BuildFastbootMenuSh(serial, toolsDir) : BuildAdbMenuSh(serial, toolsDir); + var scriptPath = Path.Combine(Path.GetTempPath(), $"atv-cli-{safe}.command"); + File.WriteAllText(scriptPath, script); + File.SetUnixFileMode( + scriptPath, + UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute | + UnixFileMode.GroupRead | UnixFileMode.GroupExecute | + UnixFileMode.OtherRead | UnixFileMode.OtherExecute); + + var psi = new ProcessStartInfo + { + FileName = "open", + WorkingDirectory = toolsDir, + UseShellExecute = false, + }; + psi.ArgumentList.Add("-a"); + psi.ArgumentList.Add("Terminal.app"); + psi.ArgumentList.Add(scriptPath); + + var process = Process.Start(psi); + if (process is not null) + { + Track(process); } } @@ -279,8 +335,92 @@ private static string BuildAdbMenu(string serial, string toolsDir) => Join(new[] "exit", }); + // macOS fastboot menu — bash equivalent of BuildFastbootMenu (universal + non-destructive only). + private static string BuildFastbootMenuSh(string serial, string toolsDir) => JoinLf(new[] + { + "#!/bin/bash", + // ANSI colors (cyan headers / green numbers / yellow values) matching the Windows menu. + "H=$'\\033[96m'; N=$'\\033[92m'; V=$'\\033[93m'; R=$'\\033[0m'", + $"export PATH=\"{ShEscape(toolsDir)}:$PATH\"", + $"SERIAL=\"{ShEscape(serial)}\"", + "while true; do", + " clear", + " echo \"${H}================ AndroidTreeView Fastboot CLI ================${R}\"", + " echo \" 设备 Device: ${V}${SERIAL}${R} (fastboot / bootloader)\"", + " echo \"${H}-------------------------------------------------------------${R}\"", + " echo \" ${N}[1]${R} 设备信息 Device info (getvar all)\"", + " echo \" ${N}[2]${R} 重启到系统 Reboot to system\"", + " echo \" ${N}[3]${R} 重启到 Bootloader Reboot to bootloader\"", + " echo \" ${N}[4]${R} 重启到 Recovery Reboot to recovery\"", + " echo \" ${N}[5]${R} 关机 Power off\"", + " echo \" ${N}[6]${R} 切换到 A 槽 Set active slot A\"", + " echo \" ${N}[7]${R} 切换到 B 槽 Set active slot B\"", + " echo \" ${N}[9]${R} 原生命令行 Raw CLI (adb + fastboot on PATH)\"", + " echo \" ${N}[0]${R} 退出 Exit\"", + " echo \"${H}-------------------------------------------------------------${R}\"", + " read -r -p \"${H}输入序号并回车 Enter choice >${R} \" sel", + " case \"$sel\" in", + " 1) fastboot -s \"$SERIAL\" getvar all; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 2) fastboot -s \"$SERIAL\" reboot; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 3) fastboot -s \"$SERIAL\" reboot bootloader; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 4) fastboot -s \"$SERIAL\" reboot recovery; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 5) fastboot -s \"$SERIAL\" oem poweroff; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 6) fastboot -s \"$SERIAL\" set_active a; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 7) fastboot -s \"$SERIAL\" set_active b; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 9) echo \"adb / fastboot 已在 PATH。输入 exit 返回菜单 (type exit to return).\"; \"${SHELL:-/bin/bash}\" ;;", + " 0) exit 0 ;;", + " esac", + "done", + }); + + // macOS adb menu — bash equivalent of BuildAdbMenu (info / shell / logcat / reboots / power / raw). + private static string BuildAdbMenuSh(string serial, string toolsDir) => JoinLf(new[] + { + "#!/bin/bash", + "H=$'\\033[96m'; N=$'\\033[92m'; V=$'\\033[93m'; R=$'\\033[0m'", + $"export PATH=\"{ShEscape(toolsDir)}:$PATH\"", + $"SERIAL=\"{ShEscape(serial)}\"", + "while true; do", + " clear", + " echo \"${H}================== AndroidTreeView ADB CLI ==================${R}\"", + " echo \" 设备 Device: ${V}${SERIAL}${R}\"", + " echo \"${H}------------------------------------------------------------${R}\"", + " echo \" ${N}[1]${R} 设备信息 Device info (getprop)\"", + " echo \" ${N}[2]${R} 进入 Shell adb shell\"", + " echo \" ${N}[3]${R} 查看日志 Logcat (Ctrl+C 停止)\"", + " echo \" ${N}[4]${R} 重启 Reboot\"", + " echo \" ${N}[5]${R} 重启到 Bootloader Reboot to bootloader\"", + " echo \" ${N}[6]${R} 重启到 Recovery Reboot to recovery\"", + " echo \" ${N}[7]${R} 关机 Power off\"", + " echo \" ${N}[9]${R} 原生命令行 Raw CLI (adb + fastboot on PATH)\"", + " echo \" ${N}[0]${R} 退出 Exit\"", + " echo \"${H}------------------------------------------------------------${R}\"", + " read -r -p \"${H}输入序号并回车 Enter choice >${R} \" sel", + " case \"$sel\" in", + " 1) adb -s \"$SERIAL\" shell getprop; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 2) adb -s \"$SERIAL\" shell ;;", + " 3) adb -s \"$SERIAL\" logcat ;;", + " 4) adb -s \"$SERIAL\" reboot; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 5) adb -s \"$SERIAL\" reboot bootloader; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 6) adb -s \"$SERIAL\" reboot recovery; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 7) adb -s \"$SERIAL\" shell reboot -p; read -n1 -s -r -p \"按任意键返回菜单 Press any key... \" ;;", + " 9) echo \"adb / fastboot 已在 PATH。输入 exit 返回菜单 (type exit to return).\"; \"${SHELL:-/bin/bash}\" ;;", + " 0) exit 0 ;;", + " esac", + "done", + }); + + // Escape for embedding a literal into a double-quoted bash string safely. + private static string ShEscape(string value) => + value.Replace("\\", "\\\\") + .Replace("\"", "\\\"") + .Replace("$", "\\$") + .Replace("`", "\\`"); + private static string Join(IEnumerable lines) => string.Join("\r\n", lines) + "\r\n"; + private static string JoinLf(IEnumerable lines) => string.Join("\n", lines) + "\n"; + private string? ResolveToolsDir() { var adb = _environment.Location?.ExecutablePath; diff --git a/src/AndroidTreeView.App/app.manifest b/src/AndroidTreeView.App/app.manifest index 5f15658..41e62b4 100644 --- a/src/AndroidTreeView.App/app.manifest +++ b/src/AndroidTreeView.App/app.manifest @@ -1,6 +1,6 @@  - + AndroidTreeView.App.mini - 1.0.5 - 1.0.5.0 - 1.0.5.0 - 1.0.5 + 1.0.6 + 1.0.6.0 + 1.0.6.0 + 1.0.6 false Assets\atv-icon.ico diff --git a/src/AndroidTreeView.Models/UpdateCheckResult.cs b/src/AndroidTreeView.Models/UpdateCheckResult.cs index e1e494c..bc6c9b3 100644 --- a/src/AndroidTreeView.Models/UpdateCheckResult.cs +++ b/src/AndroidTreeView.Models/UpdateCheckResult.cs @@ -31,7 +31,7 @@ public enum UpdateCheckStatus /// public sealed class UpdateCheckResult { - /// The version currently running (e.g. 1.0.5). + /// The version currently running (e.g. 1.0.6). public required string CurrentVersion { get; init; } /// The latest published version, when known. diff --git a/src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs b/src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs index 5ca6ec0..09d0d40 100644 --- a/src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs +++ b/src/AndroidTreeView.Shared/AndroidTreeViewSharedServices.cs @@ -1,55 +1,55 @@ -using AndroidTreeView.Adb.Services; -using AndroidTreeView.Core.Interfaces; -using AndroidTreeView.Core.Options; -using AndroidTreeView.Core.Services; -using AndroidTreeView.Infrastructure.Settings; -using AndroidTreeView.Infrastructure.Update; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.DependencyInjection.Extensions; - -namespace AndroidTreeView.Shared; - -/// -/// Shared composition root for everything the full app and Mini should run identically: ADB discovery, -/// device monitoring, scrcpy launching, settings, update checks and update installation. -/// -public static class AndroidTreeViewSharedServices -{ - public static IServiceCollection AddAndroidTreeViewSharedServices( - this IServiceCollection services, - UpdateProductOptions? updateProduct = null) - { - ArgumentNullException.ThrowIfNull(services); - - updateProduct ??= UpdateProductOptions.ForMainApp(); - - services.AddLogging(); - services.TryAddSingleton(updateProduct); - services.TryAddSingleton(sp => CreateHttpClient(sp.GetRequiredService())); - services.TryAddSingleton(); - - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - services.TryAddSingleton(); - - return services; - } - - private static HttpClient CreateHttpClient(UpdateProductOptions product) - { - var client = new HttpClient(); - client.DefaultRequestHeaders.UserAgent.ParseAdd($"{product.Name.Replace(' ', '-')}/{product.Version}"); - return client; - } -} +using AndroidTreeView.Adb.Services; +using AndroidTreeView.Core.Interfaces; +using AndroidTreeView.Core.Options; +using AndroidTreeView.Core.Services; +using AndroidTreeView.Infrastructure.Settings; +using AndroidTreeView.Infrastructure.Update; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; + +namespace AndroidTreeView.Shared; + +/// +/// Shared composition root for everything the full app and Mini should run identically: ADB discovery, +/// device monitoring, scrcpy launching, settings, update checks and update installation. +/// +public static class AndroidTreeViewSharedServices +{ + public static IServiceCollection AddAndroidTreeViewSharedServices( + this IServiceCollection services, + UpdateProductOptions? updateProduct = null) + { + ArgumentNullException.ThrowIfNull(services); + + updateProduct ??= UpdateProductOptions.ForMainApp(); + + services.AddLogging(); + services.TryAddSingleton(updateProduct); + services.TryAddSingleton(sp => CreateHttpClient(sp.GetRequiredService())); + services.TryAddSingleton(); + + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + services.TryAddSingleton(); + + return services; + } + + private static HttpClient CreateHttpClient(UpdateProductOptions product) + { + var client = new HttpClient(); + client.DefaultRequestHeaders.UserAgent.ParseAdd($"{product.Name.Replace(' ', '-')}/{product.Version}"); + return client; + } +} diff --git a/tests/AndroidTreeView.Infrastructure.Tests/GitHubUpdateServiceTests.cs b/tests/AndroidTreeView.Infrastructure.Tests/GitHubUpdateServiceTests.cs new file mode 100644 index 0000000..1731745 --- /dev/null +++ b/tests/AndroidTreeView.Infrastructure.Tests/GitHubUpdateServiceTests.cs @@ -0,0 +1,191 @@ +using System.Net; +using System.Reflection; +using System.Text; +using AndroidTreeView.Core; +using AndroidTreeView.Core.Options; +using AndroidTreeView.Infrastructure.Update; +using AndroidTreeView.Models; +using Microsoft.Extensions.Logging.Abstractions; +using Xunit; + +namespace AndroidTreeView.Infrastructure.Tests; + +public sealed class GitHubUpdateServiceTests +{ + private static GitHubUpdateService CreateService( + FakeHttpMessageHandler handler, + out FakeSettingsService settings, + string version = "1.0.6", + string? rid = "win-x64", + string assetPrefix = "AndroidTreeView") + { + settings = new FakeSettingsService(); + var product = new UpdateProductOptions + { + Version = version, + AppKey = assetPrefix == "AndroidTreeView-Mini" ? AppInfo.MiniUpdateKey : AppInfo.AppUpdateKey, + LatestReleaseApiUrl = AppInfo.LatestReleaseApiUrl, + ReleasesUrl = AppInfo.ReleasesUrl, + ReleaseAssetPrefix = assetPrefix, + ReleaseAssetRid = rid, + }; + return new GitHubUpdateService( + new HttpClient(handler), + settings, + NullLogger.Instance, + product); + } + + private static HttpResponseMessage JsonResponse(HttpStatusCode status, string body) => + new(status) { Content = new StringContent(body, Encoding.UTF8, "application/json") }; + + private static string ReleaseJson(string tag, string prefix = "AndroidTreeView") => + $$""" + { + "tag_name": "{{tag}}", + "html_url": "https://github.com/Birditch/AndroidTreeView/releases/tag/{{tag}}", + "body": "Release notes for {{tag}}.", + "assets": [ + { + "name": "{{prefix}}-2.5.1-win-x64.zip", + "browser_download_url": "https://github.com/Birditch/AndroidTreeView/releases/download/v2.5.1/{{prefix}}-2.5.1-win-x64.zip" + }, + { + "name": "{{prefix}}-2.5.1-win-x64.zip.sha256", + "browser_download_url": "https://github.com/Birditch/AndroidTreeView/releases/download/v2.5.1/{{prefix}}-2.5.1-win-x64.zip.sha256" + } + ] + } + """; + + [Fact] + public void Version_ComesFromAssemblyInformationalVersion() + { + var assembly = typeof(AppInfo).Assembly; + var expected = assembly.GetCustomAttribute()!.InformationalVersion; + Assert.Equal(expected.Split('+')[0], AppInfo.GetVersion(assembly)); + } + + [Fact] + public async Task CheckForUpdates_SameVersion_ReturnsUpToDate() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, ReleaseJson("v1.0.6"))); + var service = CreateService(handler, out _); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.Equal(UpdateCheckStatus.UpToDate, result.Status); + Assert.False(result.UpdateAvailable); + Assert.Equal("1.0.6", result.LatestVersion); + } + + [Fact] + public async Task CheckForUpdates_NewerVersion_UsesGitHubReleaseAssets() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, ReleaseJson("v2.5.1"))); + var service = CreateService(handler, out _); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.Equal(UpdateCheckStatus.UpdateAvailable, result.Status); + Assert.True(result.UpdateAvailable); + Assert.Equal("2.5.1", result.LatestVersion); + Assert.Equal("https://github.com/Birditch/AndroidTreeView/releases/tag/v2.5.1", result.ReleaseUrl); + Assert.Equal("https://github.com/Birditch/AndroidTreeView/releases/download/v2.5.1/AndroidTreeView-2.5.1-win-x64.zip", result.DownloadUrl); + Assert.Equal("https://github.com/Birditch/AndroidTreeView/releases/download/v2.5.1/AndroidTreeView-2.5.1-win-x64.zip.sha256", result.Sha256Url); + Assert.Equal("Release notes for v2.5.1.", result.ReleaseNotes); + } + + [Fact] + public async Task CheckForUpdates_Mini_UsesMiniAsset() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, ReleaseJson("v2.5.1", "AndroidTreeView-Mini"))); + var service = CreateService(handler, out _, assetPrefix: "AndroidTreeView-Mini"); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.Contains("AndroidTreeView-Mini-2.5.1-win-x64.zip", result.DownloadUrl); + } + + [Fact] + public async Task CheckForUpdates_NonWindows_LeavesInstallDisabled() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, ReleaseJson("v2.5.1"))); + var service = CreateService(handler, out _, rid: null); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.True(result.UpdateAvailable); + Assert.Null(result.DownloadUrl); + Assert.Equal("https://github.com/Birditch/AndroidTreeView/releases/tag/v2.5.1", result.ReleaseUrl); + } + + [Fact] + public async Task CheckForUpdates_SendsRequiredGitHubHeaders() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, ReleaseJson("v1.0.6"))); + var service = CreateService(handler, out _); + + await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.NotNull(handler.LastRequest); + Assert.True(handler.LastRequest!.Headers.UserAgent.Count > 0); + Assert.Contains(handler.LastRequest.Headers.Accept, h => h.MediaType == "application/vnd.github+json"); + Assert.Equal(AppInfo.LatestReleaseApiUrl, handler.LastRequest.RequestUri!.ToString()); + } + + [Theory] + [InlineData(HttpStatusCode.NotFound, UpdateCheckStatus.NoRelease)] + [InlineData(HttpStatusCode.Forbidden, UpdateCheckStatus.RateLimited)] + [InlineData(HttpStatusCode.InternalServerError, UpdateCheckStatus.NetworkError)] + public async Task CheckForUpdates_HttpFailure_ReturnsExpectedStatus(HttpStatusCode status, UpdateCheckStatus expected) + { + var handler = new FakeHttpMessageHandler(_ => new HttpResponseMessage(status)); + var service = CreateService(handler, out _); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.Equal(expected, result.Status); + Assert.False(result.UpdateAvailable); + } + + [Fact] + public async Task CheckForUpdates_InvalidTag_ReturnsInvalidData() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, ReleaseJson("not-a-version"))); + var service = CreateService(handler, out _); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.Equal(UpdateCheckStatus.InvalidData, result.Status); + } + + [Fact] + public async Task CheckForUpdates_MalformedJson_ReturnsInvalidData() + { + var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, "{ broken")); + var service = CreateService(handler, out _); + + var result = await service.CheckForUpdatesAsync(userInitiated: true); + + Assert.Equal(UpdateCheckStatus.InvalidData, result.Status); + } + + [Fact] + public async Task CheckForUpdates_DisabledAndNotUserInitiated_SkipsRequest() + { + var called = false; + var handler = new FakeHttpMessageHandler(_ => + { + called = true; + return JsonResponse(HttpStatusCode.OK, ReleaseJson("v2.5.1")); + }); + var service = CreateService(handler, out var settings); + settings.Current = new() { AutoCheckUpdates = false }; + + var result = await service.CheckForUpdatesAsync(userInitiated: false); + + Assert.Equal(UpdateCheckStatus.Disabled, result.Status); + Assert.False(called); + } +} diff --git a/tests/AndroidTreeView.Infrastructure.Tests/NekoIndexUpdateServiceTests.cs b/tests/AndroidTreeView.Infrastructure.Tests/NekoIndexUpdateServiceTests.cs deleted file mode 100644 index e0ecca1..0000000 --- a/tests/AndroidTreeView.Infrastructure.Tests/NekoIndexUpdateServiceTests.cs +++ /dev/null @@ -1,233 +0,0 @@ -using System.Net; -using System.Text; -using AndroidTreeView.Core; -using AndroidTreeView.Core.Options; -using AndroidTreeView.Infrastructure.Update; -using AndroidTreeView.Models; -using Microsoft.Extensions.Logging.Abstractions; -using Xunit; - -namespace AndroidTreeView.Infrastructure.Tests; - -public sealed class NekoIndexUpdateServiceTests -{ - private static NekoIndexUpdateService CreateService( - FakeHttpMessageHandler handler, - out FakeSettingsService settings) - { - settings = new FakeSettingsService(); - var client = new HttpClient(handler); - return new NekoIndexUpdateService(client, settings, NullLogger.Instance); - } - - private static HttpResponseMessage JsonResponse(HttpStatusCode status, string body) => - new(status) { Content = new StringContent(body, Encoding.UTF8, "application/json") }; - - private static string UpdateJson( - string version, - string downloadUrl = "/api/resources/android-tree-view-app/versions/latest/archive", - string sha256 = "0123456789abcdef", - string appKey = AppInfo.AppUpdateKey) - => $$""" - { - "ok": true, - "data": { - "appKey": "{{appKey}}", - "title": "AndroidTreeView", - "version": "{{version}}", - "releasedAt": "2026-07-08T07:40:04.829Z", - "zip": { - "size": 1344, - "sha256": "{{sha256}}", - "downloadUrl": "{{downloadUrl}}" - }, - "files": [] - }, - "error": null - } - """; - - [Fact] - public void CurrentVersion_MatchesAppInfo() - { - var service = CreateService(new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, UpdateJson("1.0.0"))), out _); - Assert.Equal(AppInfo.Version, service.CurrentVersion); - } - - [Fact] - public async Task CheckForUpdates_SameVersion_ReturnsUpToDate() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, UpdateJson(AppInfo.Version))); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.UpToDate, result.Status); - Assert.False(result.UpdateAvailable); - Assert.Equal(AppInfo.Version, result.LatestVersion); - } - - [Fact] - public async Task CheckForUpdates_NewerVersion_ReturnsUpdateAvailable() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, UpdateJson("v2.5.1"))); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.UpdateAvailable, result.Status); - Assert.True(result.UpdateAvailable); - Assert.Equal("2.5.1", result.LatestVersion); - Assert.Equal("http://192.168.89.71:14000/api/resources/android-tree-view-app/versions/latest/archive", result.ReleaseUrl); - Assert.Equal(result.ReleaseUrl, result.DownloadUrl); - Assert.Equal("0123456789abcdef", result.Sha256); - Assert.Equal("AndroidTreeView", result.ReleaseNotes); - } - - [Fact] - public async Task CheckForUpdates_SendsRequiredInternalApiHeaders() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, UpdateJson("1.0.0"))); - var service = CreateService(handler, out _); - - await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.NotNull(handler.LastRequest); - Assert.True(handler.LastRequest!.Headers.UserAgent.Count > 0); - Assert.Contains(handler.LastRequest.Headers.Accept, h => h.MediaType == "application/json"); - Assert.Equal(AppInfo.LatestReleaseApiUrl, handler.LastRequest.RequestUri!.ToString()); - } - - [Fact] - public async Task CheckForUpdates_UsesConfiguredMiniUpdateChannel() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse( - HttpStatusCode.OK, - UpdateJson("2.0.0", appKey: AppInfo.MiniUpdateKey))); - var settings = new FakeSettingsService(); - var product = UpdateProductOptions.ForMiniApp(); - var service = new NekoIndexUpdateService( - new HttpClient(handler), - settings, - NullLogger.Instance, - product); - - await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(product.LatestReleaseApiUrl, handler.LastRequest!.RequestUri!.ToString()); - } - - [Fact] - public async Task CheckForUpdates_MismatchedAppKey_ReturnsInvalidData() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse( - HttpStatusCode.OK, - UpdateJson("2.0.0", appKey: AppInfo.MiniUpdateKey))); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.InvalidData, result.Status); - Assert.False(result.UpdateAvailable); - } - - [Fact] - public async Task CheckForUpdates_Forbidden_ReturnsRateLimited() - { - var handler = new FakeHttpMessageHandler(_ => new HttpResponseMessage(HttpStatusCode.Forbidden)); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.RateLimited, result.Status); - Assert.False(result.UpdateAvailable); - } - - [Fact] - public async Task CheckForUpdates_NotFound_ReturnsNoRelease() - { - var handler = new FakeHttpMessageHandler(_ => new HttpResponseMessage(HttpStatusCode.NotFound)); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.NoRelease, result.Status); - } - - [Fact] - public async Task CheckForUpdates_NetworkFailure_ReturnsNetworkError() - { - var handler = new FakeHttpMessageHandler(_ => throw new HttpRequestException("connection refused")); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.NetworkError, result.Status); - } - - [Fact] - public async Task CheckForUpdates_InvalidVersion_ReturnsInvalidData() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, UpdateJson("not-a-version"))); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.InvalidData, result.Status); - Assert.False(result.UpdateAvailable); - } - - [Fact] - public async Task CheckForUpdates_OkFalse_ReturnsInvalidData() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, """{"ok":false,"data":null,"error":"missing"}""")); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.InvalidData, result.Status); - Assert.Equal("missing", result.ErrorMessage); - } - - [Fact] - public async Task CheckForUpdates_MalformedJson_ReturnsInvalidData() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, "{ broken")); - var service = CreateService(handler, out _); - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.InvalidData, result.Status); - } - - [Fact] - public async Task CheckForUpdates_DisabledAndNotUserInitiated_ReturnsDisabledWithoutHttpCall() - { - var called = false; - var handler = new FakeHttpMessageHandler(_ => - { - called = true; - return JsonResponse(HttpStatusCode.OK, UpdateJson("9.9.9")); - }); - var service = CreateService(handler, out var settings); - settings.Current = new AppSettings { AutoCheckUpdates = false }; - - var result = await service.CheckForUpdatesAsync(userInitiated: false); - - Assert.Equal(UpdateCheckStatus.Disabled, result.Status); - Assert.Equal(AppInfo.Version, result.CurrentVersion); - Assert.False(called); - } - - [Fact] - public async Task CheckForUpdates_DisabledButUserInitiated_StillChecks() - { - var handler = new FakeHttpMessageHandler(_ => JsonResponse(HttpStatusCode.OK, UpdateJson("3.0.0"))); - var service = CreateService(handler, out var settings); - settings.Current = new AppSettings { AutoCheckUpdates = false }; - - var result = await service.CheckForUpdatesAsync(userInitiated: true); - - Assert.Equal(UpdateCheckStatus.UpdateAvailable, result.Status); - } -}