Add docs/FEATURES.md — language-agnostic spec for v2 rewrite#21
Open
bryanroscoe wants to merge 3 commits into
Open
Add docs/FEATURES.md — language-agnostic spec for v2 rewrite#21bryanroscoe wants to merge 3 commits into
bryanroscoe wants to merge 3 commits into
Conversation
Creates docs/FEATURES.md as the canonical source of truth for what Shield Optimizer does. Catalog is structured by domain (connection, optimization, launcher, snapshot, etc.), each feature documented with purpose, behavior, exact ADB calls, edge cases, and a pointer to its v1 implementation function for traceability. The rewrite to Rust + Tauri 2 needs a language-agnostic spec rather than reverse-engineering 4,000 lines of PowerShell. This doc is that spec. Also serves as a living changelog of capabilities — PRs that add or change behavior update this doc in the same commit. README gets a one-paragraph pointer so the catalog is discoverable. No code changes.
Comprehensive verification pass against the script identified gaps in the initial catalog. Adds: §0 Invocation & startup - Command-line parameters (-ForceAdbDownload, -LightMode, -DarkMode, -Subnet) - Platform detection ($Script:Platform, $IsUnix) - Startup sequence with strict mode + terminal resize behavior §1 Connection & discovery (extended) - §1.6 Device enumeration & friendly names (Get-Devices, batched property query, Shield codename → friendly model map, USB-detection caveat for Shield) - §1.7 UNAUTHORIZED device guidance flow §2 Main menu (new section, was implicit before) - Static actions: Scan Network, Connect IP, Pair Device, Report All, Refresh, Restart ADB, Help, Quit with shortcuts - Device row selection behavior including unauthorized handling §13 Device profile & detection (expanded) - Documents the two device-type detection paths that exist in v1 (Get-DeviceType and the inline detection in Get-Devices) which use different inputs. Flag for v2 to consolidate. - Splits profile display vs detection logic §16 Cross-cutting (expanded) - §16.5 Play Store deep-link (Open-PlayStore) - §16.6 Uninstall / install error decoding (Get-UninstallErrorReason) - §16.7 Utility helpers table (Test-PackageInList, Test-AppPackage, Test-ValidIP, Format-FileSize, Get-ParsedTemperature, Get-ParsedRamInfo, Get-VitalColor, Get-VitalAnsiColor) - §16.8 Notes --user 0 convention All section numbers renumbered; all internal cross-references updated; TOC kept in sync with header set. Maintenance checklist references updated to point at the renumbered sections. No script changes.
Independent review caught seven inaccuracies in docs/FEATURES.md. Fixed: - Provenance line dropped the stale `df70dd5` commit hash — citations track current HEAD; doc now says so explicitly with a re-verify instruction for future editors. - §5.1 Health Report: the batched dumpsys parser uses per-section sentinels (`::THERMAL::`, `::MEMINFO::`, `::STORAGE::`, `::PROPS::`, `::SETTINGS::`, `::PACKAGES::`), not a single `::SECTION::` marker. The exact echo string is reproduced now so v2 can match output bytes for byte. - §14.1 Themes: macOS uses an `osascript` AppleScript snippet (not `defaults read -g AppleInterfaceStyle` — the defaults entry is stale on modern macOS). Linux has no detection at all and falls through to the dark default; that's a v2 improvement opportunity rather than a current capability. - §16.6 Get-UninstallErrorReason: documented the wrong codes. Actual function recognizes `Broken pipe`, `not installed for`, and `DELETE_FAILED_INTERNAL_ERROR`. The `INSTALL_FAILED_*` codes live inline in `Install-ApkFile` (~lines 1364-1372) — flagged for v2 consolidation. - §1.6 device returned shape: missing the `ID` field (1-based menu position used by the shortcut layer). - §7 Tweaks: enum label for match_content_frame_rate value 1 is "Seamless only", not "Seamless". - §6.2 Setup wizard: the menu also exposes "Stock Launcher" as a selectable option (with [ACTIVE]/[DISABLED]/[NOT FOUND] status tag) — re-enabling and re-activating the stock launcher is a first-class flow that wasn't documented. Behavior section now describes all menu options and exit paths. - §16.7 utility helpers table: added line-number citations for Open-PlayStore and Get-UninstallErrorReason for consistency with other entries. No behavior changes; doc only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds `docs/FEATURES.md` as the canonical source of truth for what Shield Optimizer does.
Why
We've decided on Rust + Tauri 2 for v2 (full rewrite to native installable app with auto-update + eventual mobile client). v2 needs a language-agnostic spec rather than reverse-engineering 4,000 lines of PowerShell. This is that spec.
The doc is structured by domain — connection, optimization, launcher, snapshot, etc. Every feature gets: purpose, behavior, exact ADB commands invoked, edge cases, and a function-name reference to the v1 implementation for traceability.
Also doubles as a living capability changelog. The maintenance checklist at the bottom puts the onus on PR authors to keep it current.
Contents
No code changes.