From 3db120187921db460699cb65b9b1681a2caa6d8a Mon Sep 17 00:00:00 2001 From: MR CYBER Date: Sun, 12 Jul 2026 18:33:25 -0700 Subject: [PATCH] =?UTF-8?q?feat:=20initial=20commit=20=E2=80=94=20README,?= =?UTF-8?q?=20community=20files,=20docs,=20templates,=20branding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/CODEOWNERS | 22 + .github/FUNDING.yml | 10 + .github/ISSUE_TEMPLATE/bug_report.yml | 140 +++++ .github/ISSUE_TEMPLATE/feature_request.yml | 79 +++ .github/ISSUE_TEMPLATE/support_request.yml | 80 +++ .github/PULL_REQUEST_TEMPLATE.md | 64 ++ CHANGELOG.md | 67 ++ CODE_OF_CONDUCT.md | 129 ++++ CONTRIBUTING.md | 209 +++++++ LICENSE | 21 + README.md | 691 +++++++++++++++++++++ ROADMAP.md | 101 +++ SECURITY.md | 87 +++ SUPPORT.md | 85 +++ assets/favicon.svg | 16 + assets/logo-dark.svg | 23 + assets/logo-light.svg | 23 + assets/logo.svg | 32 + docs/adb.md | 165 +++++ docs/architecture.md | 301 +++++++++ docs/cli-reference.md | 158 +++++ docs/developer-guide.md | 211 +++++++ docs/installation.md | 157 +++++ docs/repair.md | 132 ++++ docs/troubleshooting.md | 344 ++++++++++ docs/uninstall.md | 144 +++++ docs/webdav.md | 204 ++++++ 27 files changed, 3695 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/support_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 ROADMAP.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 assets/favicon.svg create mode 100644 assets/logo-dark.svg create mode 100644 assets/logo-light.svg create mode 100644 assets/logo.svg create mode 100644 docs/adb.md create mode 100644 docs/architecture.md create mode 100644 docs/cli-reference.md create mode 100644 docs/developer-guide.md create mode 100644 docs/installation.md create mode 100644 docs/repair.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/uninstall.md create mode 100644 docs/webdav.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..69aee8e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,22 @@ +# Default owners for everything in the repo +# Each line is a file pattern followed by one or more owners + +# Global owners +* @gshellmr-code + +# Build pipeline +build/ @gshellmr-code +*.nsi @gshellmr-code +*.spec @gshellmr-code +build.bat @gshellmr-code +build2.bat @gshellmr-code + +# Native modules +native/ @gshellmr-code + +# Documentation +docs/ @gshellmr-code +*.md @gshellmr-code + +# CI/CD +.github/ @gshellmr-code diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..5b4e983 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,10 @@ +# These are supported funding model platforms + +github: [gshellmr-code] +# ko_fi: # Replace with a single Ko-fi username +# open_collective: # Replace with a single Open Collective username +# patreon: # Replace with a single Patreon username +# community_bridge: # Replace with a single Community Bridge project name +# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] +custom: + - https://buymeacoffee.com/mrcyberdev diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..c813613 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,140 @@ +name: Bug Report +description: Report a bug in WSA Installer +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thank you for reporting a bug! Please fill out the form below to help us identify and fix the issue. + + - type: dropdown + id: component + attributes: + label: Component + description: Which part of WSA Installer is affected? + options: + - Installation (WSA setup) + - Play Store integration + - Background Service + - File Sharing (WebDAV) + - Repair flow + - Uninstall flow + - Self-Update + - UI / GUI + - System Detection + - Other + validations: + required: true + + - type: input + id: version + attributes: + label: WSA Installer Version + description: "Find this in the About section or title bar" + placeholder: "e.g., 1.2.0.0" + validations: + required: true + + - type: input + id: os + attributes: + label: Windows Version + description: "e.g., Windows 11 23H2, Windows 10 22H2" + placeholder: "e.g., Windows 11 23H2" + validations: + required: true + + - type: input + id: hardware + attributes: + label: Hardware Info (optional) + description: "CPU, RAM, and any relevant hardware details" + placeholder: "e.g., Intel i7-12700K, 16GB RAM" + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of the bug. + placeholder: Describe the bug... + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. Open WSA Installer + 2. Click on '...' + 3. Scroll down to '...' + 4. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What you expected to happen. + placeholder: Describe what you expected... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened. + placeholder: Describe what actually happened... + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant Logs + description: "Paste any relevant log output. Check `wsa_activity.log` for session logs." + render: shell + + - type: textarea + id: screenshots + attributes: + label: Screenshots (optional) + description: If applicable, add screenshots to help explain the problem. + + - type: dropdown + id: install-method + attributes: + label: Installation Method + options: + - NSIS Installer (WSA_Installer_Setup.exe) + - Build from source (run.bat) + - Portable (direct run) + validations: + required: true + + - type: dropdown + id: playstore + attributes: + label: Play Store Installed? + options: + - "Yes" + - "No" + - Attempted but failed + validations: + required: true + + - type: checkboxes + id: terms + attributes: + label: Checklist + options: + - label: I have searched existing issues to avoid duplicates + required: true + - label: I have checked the troubleshooting guide + required: false + - label: I have attached relevant log files + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..9ed992b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,79 @@ +name: Feature Request +description: Suggest a new feature for WSA Installer +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thank you for suggesting a feature! Please fill out the form below. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: "What problem does this feature solve? Is it related to a frustration?" + placeholder: "I'm always frustrated when..." + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like. + placeholder: "I'd like WSA Installer to..." + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Describe any alternative solutions or features you've considered. + + - type: dropdown + id: component + attributes: + label: Component + description: Which part of WSA Installer does this affect? + options: + - Installation flow + - WSA management + - Play Store integration + - File sharing (WebDAV) + - Background service + - UI / GUI + - Build system + - Documentation + - Other + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Nice to have + - Important + - Critical (blocking my workflow) + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional Context + description: Add any other context, screenshots, or examples about the feature request. + + - type: checkboxes + id: terms + attributes: + label: Checklist + options: + - label: I have searched existing feature requests to avoid duplicates + required: true + - label: I would be willing to help implement this feature + required: false diff --git a/.github/ISSUE_TEMPLATE/support_request.yml b/.github/ISSUE_TEMPLATE/support_request.yml new file mode 100644 index 0000000..c3e8005 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/support_request.yml @@ -0,0 +1,80 @@ +name: Support Request +description: Get help with WSA Installer +title: "[Help]: " +labels: ["question", "help wanted"] +body: + - type: markdown + attributes: + value: | + Need help with WSA Installer? Please provide as much detail as possible. + + - type: dropdown + id: topic + attributes: + label: Help Topic + options: + - Installation issues + - Play Store issues + - WSA won't start + - Background service issues + - File sharing (WebDAV) + - Repair / Uninstall + - Update issues + - General usage + - Other + validations: + required: true + + - type: input + id: version + attributes: + label: WSA Installer Version + placeholder: "e.g., 1.2.0.0" + validations: + required: true + + - type: input + id: os + attributes: + label: Windows Version + placeholder: "e.g., Windows 11 23H2" + validations: + required: true + + - type: textarea + id: question + attributes: + label: Your Question + description: Describe what you need help with. + placeholder: "I'm trying to..." + validations: + required: true + + - type: textarea + id: what-tried + attributes: + label: What Have You Tried? + description: Describe what you've already attempted. + + - type: textarea + id: logs + attributes: + label: Relevant Logs (optional) + description: "Paste any relevant log output from `wsa_activity.log` or the UI." + render: shell + + - type: textarea + id: screenshots + attributes: + label: Screenshots (optional) + description: Add screenshots if applicable. + + - type: checkboxes + id: terms + attributes: + label: Checklist + options: + - label: I have checked the troubleshooting guide + required: true + - label: I have searched existing issues for similar questions + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ae47b31 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,64 @@ +--- +name: Pull Request +about: Submit changes to WSA Installer +title: '' +labels: '' +assignees: '' +--- + +## Description + + + +## Type of Change + + + +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Refactoring (code changes that neither fix a bug nor add a feature) +- [ ] Performance improvement +- [ ] Build / CI change + +## Related Issues + + + +Closes #(issue number) + +## Changes Made + + + +- Change 1 +- Change 2 +- Change 3 + +## Testing + + + +- [ ] Tested on Windows 10 +- [ ] Tested on Windows 11 +- [ ] Tested with Play Store installation +- [ ] Tested repair flow +- [ ] Tested uninstall flow +- [ ] Tested background service +- [ ] Tested file sharing (WebDAV) +- [ ] Tested self-update + +## Screenshots + + + +## Checklist + +- [ ] My code follows the project's code style +- [ ] I have self-reviewed my code +- [ ] I have added comments for complex logic +- [ ] I have updated documentation as needed +- [ ] I have added tests that prove my fix is effective or my feature works +- [ ] New and existing tests pass locally with my changes +- [ ] Any dependent changes have been merged and published diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3751d6b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,67 @@ +# Changelog + +All notable changes to WSA Installer will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.2.0] - 2026-07-12 + +### Added +- File sharing via WebDAV (user and root modes) +- Drive mounting as Windows network drives +- Advanced settings page with file sharing controls +- Auto-repair toggle in advanced settings +- Background service GUI monitor dialog +- 30-chunk parallel download for self-updates +- Download resume support across sessions +- Drive letter selection for WebDAV mounts +- Custom drive labels and icons via registry + +### Changed +- Upgraded to Python 3.14 +- Improved download speed with parallel chunks +- Enhanced error handling with retry logic +- Updated NSIS installer with maintenance mode +- Improved glass transparency system + +### Fixed +- WsaClient.exe crash on Windows 10 (WSAPatch) +- ADB authorization popup automation reliability +- Service auto-restart on failure +- Single-instance lock release on uninstall + +## [1.1.0] - 2026-06-01 + +### Added +- Background service (`WSABackgroundService`) +- Windows Service integration with auto-restart +- Remote configuration via Rust security gateway +- Self-update mechanism +- Repair flow from Windows Settings +- YouTube channel subscription on completion + +### Changed +- Improved system detection (5 methods) +- Enhanced Play Store patching with 7-phase flow +- Better progress tracking with phase headers + +### Fixed +- Virtualization detection on certain hardware +- Hyper-V enabling on Windows 10 + +## [1.0.0] - 2026-05-01 + +### Added +- Initial release +- 5-step installation wizard +- System detection (virtualization, Hyper-V, VMP, WSL) +- WSA download with parallel chunks +- 7z extraction with nested folder detection +- 6-phase WSA installation +- 7-phase Play Store integration +- ADB authorization automation +- Glass transparency UI +- NSIS professional installer +- Silent installation support +- Single-instance enforcement diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b503f14 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,129 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at the +[GitHub Issues](https://github.com/WSA-Installer/wsa-installer/issues). + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b27d8c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,209 @@ +# Contributing to WSA Installer + +Thank you for your interest in contributing to WSA Installer! This document provides guidelines and information for contributors. + +## Code of Conduct + +By participating in this project, you agree to maintain a respectful and inclusive environment for everyone. Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing. + +## How Can I Contribute? + +### Reporting Bugs + +Before creating a bug report, please check [existing issues](https://github.com/WSA-Installer/wsa-installer/issues) to avoid duplicates. + +When creating a bug report, include: + +- **Clear title** — Describe the issue concisely +- **WSA Installer version** — Found in the About section +- **Windows version** — e.g., Windows 11 23H2 +- **Steps to reproduce** — Detailed steps to trigger the bug +- **Expected behavior** — What you expected to happen +- **Actual behavior** — What actually happened +- **Logs** — Relevant log output from `wsa_activity.log` or the UI log + +### Suggesting Features + +Feature suggestions are welcome! Please provide: + +- **Problem statement** — What problem does this solve? +- **Proposed solution** — How should it work? +- **Alternatives considered** — Other approaches you thought about +- **Component** — Which part of the installer does this affect? + +### Pull Requests + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/my-feature` +3. Make your changes +4. Test thoroughly on Windows 10 and/or Windows 11 +5. Commit with a descriptive message +6. Push to your fork +7. Open a Pull Request + +## Development Setup + +### Prerequisites + +- Python 3.14 +- Windows 10/11 +- Administrator privileges (for testing) +- Git + +### Getting Started + +```bash +# Clone the repository +git clone https://github.com/WSA-Installer/wsa-installer.git +cd wsa-installer + +# Run the development launcher +run.bat +``` + +The `run.bat` script will: +1. Create a Python virtual environment if it doesn't exist +2. Install all dependencies from `requirements.txt` +3. Launch the application + +### Project Structure + +``` +wsa-installer/ +├── src/ +│ ├── app.py # Main application (~11K lines) +│ ├── run.py # Entry point +│ ├── WSARepair.py # Windows Settings proxy +│ └── patch_flet.py # Flet client patcher +├── assets/ # Runtime resources +├── native/ # Rust native modules +├── emb_py/ # Embedded Python 3.14 +├── build/ # Build scripts +├── docs/ # Documentation +└── tests/ # Tests +``` + +### Key Files + +- **`app.py`** — The main application file containing the Flet GUI, installer logic, background service, repair, update, and file sharing functionality +- **`WSARepair.py`** — Proxy for Windows Settings Repair/Uninstall buttons +- **`build.bat`** — Primary build pipeline (Nuitka → PyInstaller → NSIS) + +## Code Style + +### Python + +- Follow [PEP 8](https://peps.python.org/pep-0008/) style guide +- Use meaningful variable and function names +- Add docstrings for public functions and classes +- Keep functions focused and concise +- Use type hints where appropriate + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/) format: + +``` +(): + +Types: + feat - New feature + fix - Bug fix + docs - Documentation changes + style - Code style changes (formatting, etc.) + refactor - Code refactoring + perf - Performance improvements + test - Adding or updating tests + build - Build system changes + ci - CI/CD changes + chore - Maintenance tasks + +Scopes: + installer - Main installer + service - Background service + webdav - File sharing + ui - User interface + build - Build pipeline + docs - Documentation +``` + +Examples: +``` +feat(installer): add parallel chunked download with resume +fix(service): resolve WSA port detection timeout +docs(readme): update installation guide +build(nsis): add silent install support +``` + +### Branch Naming + +- `feature/description` — New features +- `fix/description` — Bug fixes +- `docs/description` — Documentation changes +- `release/version` — Release preparation + +## Testing + +### Manual Testing + +Before submitting a PR, test the following flows: + +1. **Fresh Install** — Install WSA on a clean system +2. **Play Store** — Verify Play Store integration works +3. **Repair** — Test the repair flow from Windows Settings +4. **Uninstall** — Verify complete uninstallation +5. **Update** — Test the self-update mechanism +6. **File Sharing** — Test WebDAV drive mounting + +### Test Checklist + +- [ ] Tested on Windows 10 (build 19041+) +- [ ] Tested on Windows 11 +- [ ] Tested with Play Store installation +- [ ] Tested repair flow +- [ ] Tested uninstall flow +- [ ] No new warnings or errors +- [ ] UI renders correctly at different DPI settings + +## Building + +### Development Build + +```cmd +run.bat +``` + +### Release Build + +```cmd +build.bat +``` + +This will produce `dist/WSA_Installer_Setup.exe`. + +### Build Requirements + +- Python 3.14 with pip +- Nuitka (`pip install nuitka`) +- PyInstaller (`pip install pyinstaller`) +- NSIS ([nsis.sourceforge.io](https://nsis.sourceforge.io)) + +## Documentation + +- Update `docs/` if adding new features +- Update `README.md` if changing public API or behavior +- Add entries to `CHANGELOG.md` for notable changes +- Update `ROADMAP.md` if adding planned features + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). + +## Questions? + +If you have questions about contributing, feel free to: + +- Open a [Discussion](https://github.com/WSA-Installer/wsa-installer/discussions) +- Contact via [YouTube](https://www.youtube.com/@AT_Tech_Zone) + +Thank you for contributing to WSA Installer! diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9ec0135 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 AT Tech Zone + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..9168c94 --- /dev/null +++ b/README.md @@ -0,0 +1,691 @@ +
+ + + + + WSA Installer + + +# WSA Installer + +### The Modern Windows Subsystem for Android Installation & Management Toolkit + +![Version](https://img.shields.io/badge/version-1.2.0.0-blue?style=for-the-badge) +![WSA Build](https://img.shields.io/badge/WSA-2407.40000.4.0-green?style=for-the-badge) +![Python](https://img.shields.io/badge/Python-3.14-3776AB?style=for-the-badge&logo=python&logoColor=white) +![Rust](https://img.shields.io/badge/Rust-Native-000000?style=for-the-badge&logo=rust&logoColor=white) +![Platform](https://img.shields.io/badge/Platform-Windows_10%2F11-0078D4?style=for-the-badge&logo=windows&logoColor=white) +![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge) + +**A complete solution for installing Windows Subsystem for Android with Google Play Store on Windows 10/11.** + +Built with care by [AT Tech Zone](https://www.youtube.com/@AT_Tech_Zone) — MR CYBER + +[Download WSA Installer (228 MB)](https://github.com/WSA-Installer/wsa-installer/releases/latest) · [Download Bundle (1.21 GB)](https://github.com/WSA-Installer/wsa-installer/releases/latest) + +
+ +--- + +## Table of Contents + +- [Introduction](#introduction) +- [Features](#features) +- [System Requirements](#system-requirements) +- [Installation](#installation) +- [The WSA Bundle](#the-wsa-bundle) +- [Architecture](#architecture) +- [CLI Reference](#cli-reference) +- [WSA WebDev — Android WebDAV Server](#wsa-webdev--android-webdav-server) +- [Configuration](#configuration) +- [Troubleshooting](#troubleshooting) +- [Build from Source](#build-from-source) +- [Tech Stack](#tech-stack) +- [Roadmap](#roadmap) +- [Contributing](#contributing) +- [Credits](#credits) +- [License](#license) +- [Support](#support) + +--- + +## Introduction + +**WSA Installer** is a professional-grade, open-source tool that automates the entire process of installing **Windows Subsystem for Android (WSA)** with or without **Google Play Store** on Windows 10 and Windows 11. + +Installing WSA manually involves downloading large archives, extracting them with specific tools, configuring Windows features, patching settings files, and optionally integrating Google Apps — a process that can take hours and requires technical expertise. WSA Installer eliminates all of that complexity with a **one-click installation experience**. + +### What WSA Installer Does + +| Capability | Description | +|:-----------|:------------| +| **System Detection** | Automatically scans your system for VT-x/AMD-V virtualization, Hyper-V, VirtualMachinePlatform, HypervisorPlatform, and WSL support | +| **Feature Enabling** | Enables all required Windows features automatically with administrator privileges | +| **WSA Download** | Downloads the correct WSA build from GitHub Releases with parallel chunked downloads and resume support | +| **WSA Installation** | Extracts, configures, and registers the Android subsystem with proper Developer Mode settings | +| **Play Store Integration** | Patches Google Apps (MindTheGapps 13.0) onto the WSA installation with automated ADB authorization | +| **WSAPatch Fix** | Applies binary patches to `WsaClient.exe` for Windows 10 compatibility (crash fix) | +| **Background Service** | Installs `WSABackgroundService` — a Windows Service that monitors WSA status and manages the Play Store SDK | +| **Self-Update** | Checks the server for updates and installs them silently without user intervention | +| **Uninstall** | Provides complete WSA removal including services, files, and registry entries | + +### Who Is This For? + +- **End Users** who want to run Android apps on Windows without technical knowledge +- **Developers** who need Android emulation for testing +- **Power Users** who want a clean, automated WSA setup with Play Store +- **Anyone** who wants to avoid the complexity of manual WSA installation + +--- + +## Features + +### Core Features + +| Feature | Description | +|:--------|:------------| +| Smart System Scan | Detects VT-x, Hyper-V, VirtualMachinePlatform, HypervisorPlatform, WSL in real-time | +| Auto Configuration | Enables required Windows features automatically with admin privileges | +| One-Click Install | Handles download, extraction, and setup end-to-end | +| Play Store Patching | Applies Run.bat, WsaClient.exe, ps.ico patches automatically via Rust SDK | +| WSAPatch Fix | Binary patches WsaClient.exe for compatibility on Windows 10 | +| Background Service | `WSABackgroundService` monitors WSA status and manages the SDK | +| Self-Update | Checks server for updates and installs silently | +| Developer Mode | Enabled automatically for advanced usage and ADB access | + +### Installer Features + +| Feature | Description | +|:--------|:------------| +| NSIS Professional Setup | Industry-standard Windows installer with wizard UI | +| Silent Mode | Full `/S` silent install support for automation | +| Maintenance Mode | Repair, reinstall, or uninstall from existing installation | +| UAC Elevation | Automatic administrator privilege request | +| Single Instance | Mutex-based prevents running multiple installer copies | +| Windows 10 Check | Validates minimum OS build before installation | + +### UI Features + +| Feature | Description | +|:--------|:------------| +| Flet-Based GUI | Modern cross-platform UI framework | +| Glass Transparency | Alpha-blended window transparency (configurable 0-100) | +| 5-Step Wizard | Guided installation flow: Intro → Check → Install → Play Store → Complete | +| Real-Time Progress | Live download progress with speed and ETA | +| Remote Config | Server-side configuration updates without app changes | + +### Developer Features + +| Feature | Description | +|:--------|:------------| +| Source Protection | Nuitka compilation + PyInstaller bundling | +| Rust Native Modules | `widget_ui.pyd` (security gateway) + `playstore_patcher_mem.pyd` (SDK) | +| Embedded Python 3.14 | Self-contained runtime for Play Store patcher | +| Activity Logging | Session-based logging to `wsa_activity.log` | +| Config Controller | Source-tracked configuration (default → dev → server) | + +--- + +## System Requirements + +| Requirement | Minimum | Recommended | +|:------------|:--------|:------------| +| OS | Windows 10 (build 19041+) or Windows 11 | Windows 11 22H2+ | +| RAM | 8 GB | 16 GB | +| Disk Space | 10 GB free | SSD with 20 GB free | +| Internet | Required for initial download only | Broadband recommended | +| Privileges | Administrator | Administrator | +| Virtualization | Enabled in BIOS/UEFI | Intel VT-x or AMD-V | + +### Windows Features Required + +| Feature | Status | How Installer Handles It | +|:--------|:-------|:-------------------------| +| Hyper-V | Must be enabled | Auto-enabled by installer | +| VirtualMachinePlatform | Must be enabled | Auto-enabled by installer | +| HypervisorPlatform | Must be enabled | Auto-enabled by installer | +| Windows Subsystem for Linux | Must be enabled | Auto-enabled by installer | + +--- + +## Installation + +### Step 1 — Download + +Download the WSA Installer setup file from the official release: + +| File | Size | Link | +|:-----|:-----|:-----| +| `WSA_Installer_Setup.exe` | 228 MB | [Download](https://github.com/WSA-Installer/wsa-installer/releases/latest) | +| `bundle.wsa` (optional) | 1.21 GB | [Download](https://github.com/WSA-Installer/wsa-installer/releases/latest) | + +> **Note:** The `bundle.wsa` file is optional. If not provided, the installer will download WSA packages directly from GitHub during installation. + +### Step 2 — Run Installer + +1. Right-click `WSA_Installer_Setup.exe` and select **Run as administrator** +2. Accept the UAC (User Account Control) prompt +3. The installer wizard will launch with the Welcome page + +**Silent Install (Advanced):** +```cmd +WSA_Installer_Setup.exe /S +``` + +### Step 3 — System Check + +The installer automatically scans your system for: + +- **Virtualization Support** — Intel VT-x or AMD-V (detected via 5 methods: CPUID, wmic, systeminfo, PowerShell, registry) +- **Hyper-V** — Microsoft's hardware virtualization +- **VirtualMachinePlatform** — Required for WSA +- **HypervisorPlatform** — Hypervisor interface +- **WSL** — Windows Subsystem for Linux + +If any required features are missing, the installer will offer to enable them automatically. + +### Step 4 — Install WSA + +The installer proceeds through 6 phases: + +| Phase | Action | +|:------|:-------| +| 1. Locate | Finds WSA package (from bundle or GitHub download) | +| 2. Verify | Validates archive integrity and checksum | +| 3. Prepare | Extracts 7z archive, copies files to installation directory | +| 4. Patch | Applies Developer Mode settings, registry fixes, WsaClient patches | +| 5. Run | Registers WSA with Windows, starts the subsystem | +| 6. Finalize | Creates shortcuts, configures background service | + +### Step 5 — Add Play Store + +If you selected the Play Store option, the installer proceeds through 7 additional phases: + +| Phase | Action | +|:------|:-------| +| 1. Locate | Finds GApps package (MindTheGapps 13.0) | +| 2. Verify | Validates GApps archive | +| 3. Extract | Extracts GApps to temporary directory | +| 4. Patch | Runs MagiskOnWSALocal patching (Run.bat + patches) | +| 5. ADB | Automates ADB authorization via pywinauto GUI automation | +| 6. Install | Pushes GApps to WSA via ADB | +| 7. Finalize | Applies Play Store icon, cleans up, restarts WSA | + +### Step 6 — Complete + +Once installation is complete: + +- **Play Store** shortcut appears in Start Menu +- **Windows Subsystem for Android** shortcut appears on Desktop +- **WSABackgroundService** is running and monitoring WSA status +- You can now launch Android apps directly from the Start Menu + +--- + +## The WSA Bundle + +### Overview + +The WSA Bundle (`bundle.wsa`) is a **pre-packaged archive** that combines both the WSA Basic package and the WSA + Google Play Store package into a single downloadable asset. + +### What's Included + +#### 1. Base Package (WSA Basic) + +| Component | Version / Notes | +|:----------|:----------------| +| WSA Build | 2407.40000.4.0 | +| Channel | Nightly Release | +| Architecture | x64 | +| Google Play Store | Not included | +| Amazon Appstore | Not included | + +#### 2. Play Store Package (WSA + GApps) + +| Component | Version / Notes | +|:----------|:----------------| +| WSA Build | 2407.40000.4.0 | +| Channel | Nightly Release | +| Architecture | x64 | +| Google Play Store | Included (MindTheGapps 13.0) | +| Amazon Appstore | Not included | + +> Both packages are based on the official WSABuilds release from [MustardChef/WSABuilds](https://github.com/MustardChef/WSABuilds). + +### Why a Bundle? + +| Benefit | Description | +|:--------|:------------| +| Single download | One file instead of two | +| Faster install | Reduced overall installation time | +| Offline access | Both packages remain available offline | +| No redundancy | No redundant network requests | + +--- + +## Architecture + +### Application Architecture + +```mermaid +graph TB + subgraph "Frontend (Flet GUI)" + WIZARD[5-Step Wizard] + OVERLAY[Overlays
About, Advanced, Download] + SB[Sidebar Navigation] + end + + subgraph "Core Engine" + IL[InstallerLogic] + CC[ConfigController] + RCM[RemoteConfigManager] + end + + subgraph "Native Security" + WU[widget_ui.pyd
Rust Gateway] + PS[playstore_patcher_mem.pyd
Play Store SDK] + end + + subgraph "System Integration" + SVC[WSABackgroundService
Windows SCM] + ADB[ADB Bridge
Port 58526] + WSA[Windows Subsystem
for Android] + EMB[Embedded Python 3.14] + end + + subgraph "External" + GH[GitHub Releases] + SERVER[Remote Config Server] + end + + WIZARD --> IL + OVERLAY --> IL + SB --> WIZARD + IL --> CC + IL --> RCM + IL --> WU + IL --> PS + IL --> ADB + ADB --> WSA + PS --> EMB + SVC --> WSA + RCM --> WU + RCM --> SERVER + IL --> GH +``` + +### Security Architecture + +``` +┌──────────────────────────────────────────────────────┐ +│ Security Layers │ +├──────────────────────────────────────────────────────┤ +│ │ +│ Layer 1: widget_ui.pyd (Rust) │ +│ ├── Zero-trust config gateway │ +│ ├── Signature verification │ +│ └── Encrypted config parsing │ +│ │ +│ Layer 2: Socket-based Instance Locks │ +│ ├── Single instance enforcement │ +│ └── Port-based process detection │ +│ │ +│ Layer 3: Windows Service │ +│ ├── SYSTEM-level service (WSABackgroundService) │ +│ ├── Auto-restart on failure │ +│ └── User session process spawning │ +│ │ +│ Layer 4: Source Protection │ +│ ├── Nuitka compilation (app.py → app.pyd) │ +│ ├── PyInstaller bundling │ +│ └── Binary string obfuscation │ +│ │ +└──────────────────────────────────────────────────────┘ +``` + +### Installation Flow + +```mermaid +flowchart TD + A[Start] --> B{Admin?} + B -->|No| C[Request Elevation] + C --> D{Admin?} + D -->|No| E[Exit] + D -->|Yes| F[System Check] + B -->|Yes| F + F --> G[Virtualization?] + G -->|No| H[Enable Features] + H --> G + G -->|Yes| I[Check Bundle] + I -->|Found| J[Extract Bundle] + I -->|Not Found| K[Download from GitHub] + K --> J + J --> L[Install WSA] + L --> M{Play Store?} + M -->|Yes| N[7-Phase Play Store] + M -->|No| O[Complete] + N --> O + O --> P[Create Shortcuts] + P --> Q[Start Service] + Q --> R[Done] +``` + +--- + +## CLI Reference + +### Command Line Arguments + +| Argument | Description | +|:---------|:------------| +| `--install-service` | Install WSABackgroundService | +| `--uninstall-service` | Remove WSABackgroundService | +| `--bg-service` | Run as background service (SYSTEM context) | +| `--bg-service-gui` | Background service with visible console | +| `--uninstall` | Launch uninstall dialog | +| `--update ` | Self-update dialog | +| `--repair-wsa` | 4-step WSA repair (detect → stop → backup → reinstall) | +| `--file-sharing` | File sharing (WebDAV mount) dialog | +| `--ad ` | Spawn ad overlay | +| `--sdk` | Start Play Store patcher SDK | + +### Silent Installation + +```cmd +WSA_Installer_Setup.exe /S +``` + +### Repair from Windows Settings + +```cmd +WSA_Installer_Setup.exe /S /repair +``` + +--- + +## WSA WebDev — Android WebDAV Server + +The `WSA WebDev` project is a complete **Android WebDAV Server** that runs inside WSA, providing file system access from your PC's web browser. + +### Features + +| Feature | Description | +|:--------|:------------| +| WebDAV Protocol | Full WebDAV server (OPTIONS, GET, PUT, DELETE, MKCOL, COPY, MOVE, PROPFIND, PROPPATCH, LOCK, UNLOCK) | +| Root Access | Supports root filesystem operations via `su` | +| Web File Manager | Complete SPA with dark/light themes, grid/list views, drag-and-drop | +| ADB Commands | Remote control via ADB intents (START, STOP, RESTART, STATUS, HEALTH) | +| Auto-Start | Boot receiver for automatic startup | +| Health Monitoring | 30-second interval health checks | + +> See the [wsa-webdav](https://github.com/WSA-Installer/wsa-webdav) repository for full documentation. + +--- + +## Configuration + +### Remote Configuration + +The installer fetches remote JSON configuration from the server on a timer. Configuration is managed by `ConfigController` with source tracking: + +``` +Default Config → Dev Mode Config → Server Config +``` + +### Config Sources + +| Source | Priority | Description | +|:-------|:---------|:------------| +| Default | 1 | Built-in application defaults | +| Dev Mode | 2 | Developer mode overrides (if enabled) | +| Server | 3 | Remote configuration updates | + +### Security Gateway + +The `widget_ui.pyd` Rust module provides: + +- Zero-trust config parsing with signature verification +- Encrypted configuration handling +- Hash-based deduplication +- Fallback mechanisms for offline scenarios + +--- + +## Troubleshooting + +### Common Issues + +| Issue | Solution | +|:------|:---------| +| Virtualization not detected | Enable VT-x/AMD-V in BIOS/UEFI | +| Hyper-V won't enable | Check if WSL2 is installed, run `bcdedit /set hypervisorlaunchtype auto` | +| Download fails | Check internet connection, try manually downloading bundle.wsa | +| Play Store not working | Ensure ADB authorization completed, check Developer Mode is enabled | +| WsaClient.exe crashes (Win10) | WSAPatch fix is applied automatically; manual patch available | +| Service won't start | Run `WSA Installer.exe --install-service` as administrator | + +### Logs + +- **Activity Log:** `wsa_activity.log` — Session-based activity logging +- **Application Logs:** Written to `sys.__stdout__` with `[APP LOGS]` prefix + +### Manual WSA Kill + +If WSA gets stuck: + +```cmd +taskkill /F /IM WsaService.exe +taskkill /F /IM WsaClient.exe +taskkill /F /IM WsaSettings.exe +``` + +--- + +## Build from Source + +### Prerequisites + +- Python 3.14 +- Node.js (for yt-dlp embedded in emb_py) +- Nuitka (`pip install nuitka`) +- PyInstaller (`pip install pyinstaller`) +- NSIS ([nsis.sourceforge.io](https://nsis.sourceforge.io)) + +### Primary Build + +```cmd +build.bat +``` + +Build pipeline: + +``` +Step 1: Clean + └── Removes dist/, build/, app.pyd, *.build + +Step 2: Dependencies + └── pip install -r requirements.txt + +Step 3: Version Update + └── PowerShell replaces version in app.py + file_version_info.txt + +Step 4: Nuitka Module + ├── Compiles app.py → app.pyd (module mode, source protection) + └── Renames app.py → wsa.py to hide source + +Step 5: PyInstaller Onedir + ├── Uses WSA_Installer_Download_onedir.spec + └── Restores app.py from wsa.py after build + +Step 6: WSARepair.exe + └── PyInstaller --onefile + +Step 7: Flet Client Patch + ├── Patches flet.exe icon + version info + └── Creates patched flet-windows.zip + +Step 8: NSIS Installer + └── Builds WSA_Installer_Setup.exe +``` + +### Alternate Build + +```cmd +build2.bat +``` + +Uses Nuitka standalone mode with C# launcher compilation. + +--- + +## Tech Stack + +### Core Technologies + +| Technology | Version | Usage | +|:-----------|:--------|:------| +| Python | 3.14 | Application framework with Flet UI | +| Rust | Latest | Security gateway (`widget_ui.pyd`) and SDK (`playstore_patcher_mem.pyd`) | +| Flet | Latest | Cross-platform GUI framework | +| PyQt6 | Latest | Embedded Python runtime for Play Store patcher | + +### Build Tools + +| Tool | Usage | +|:-----|:------| +| Nuitka | Python to C compilation (source protection) | +| PyInstaller | Application bundling (onedir mode) | +| NSIS | Windows installer packaging | +| C# / PowerShell | Launcher compilation | + +### Dependencies + +| Package | Purpose | +|:--------|:--------| +| requests | HTTP client for downloads | +| flet | Cross-platform UI framework | +| pyautogui | GUI automation | +| pyperclip | Clipboard operations | +| pywinauto | Windows UI Automation (ADB authorization) | +| PyQt6 | Qt6 bindings (ads browser) | +| PyQt6-WebEngine | Chromium web engine | +| pycryptodomex | Cryptography | +| pillow | Image processing | +| comtypes | COM interface access | +| psutil | Process/system utilities | +| brotli | Compression | +| inflate64 | 64-bit inflate compression | +| multivolumefile | Multi-volume archives | +| pybcj | Blosc2 compression | +| pyppmd | PPMD compression | +| texttable | Text table formatting | +| pywin32 | Win32 API access | +| packaging | Version parsing | + +### Native Modules + +| Module | Language | Purpose | +|:-------|:---------|:--------| +| `widget_ui.pyd` | Rust | Zero-trust security gateway | +| `playstore_patcher_mem.pyd` | Rust | Play Store patcher SDK | + +--- + +## Roadmap + +### Current (v1.2.x) + +- [x] One-click WSA installation +- [x] Play Store integration +- [x] Background service +- [x] Self-update system +- [x] Repair and uninstall flows +- [x] File sharing (WebDAV) +- [x] Glass transparency UI +- [x] Remote configuration +- [x] NSIS professional installer + +### Planned + +- [ ] WSA version management (install multiple versions) +- [ ] Custom GApps selection (NikGapps, FlameGApps) +- [ ] WSA settings backup and restore +- [ ] ADB shell integration in UI +- [ ] Performance monitoring dashboard +- [ ] Automatic Hyper-V configuration +- [ ] WSA app data export/import +- [ ] Multi-language support (i18n) +- [ ] Dark/light theme toggle +- [ ] Command-line batch operations +- [ ] MSI installer alternative +- [ ] Winget/Chocolatey/Scoop packages + +--- + +## Contributing + +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. + +### Quick Start for Contributors + +```bash +# 1. Fork the repository +# 2. Clone your fork +git clone https://github.com/YOUR_USERNAME/wsa-installer.git + +# 3. Create a feature branch +git checkout -b feature/my-feature + +# 4. Make your changes +# 5. Test with run.bat + +# 6. Commit and push +git commit -m "feat(scope): add my feature" +git push origin feature/my-feature + +# 7. Create a Pull Request +``` + +--- + +## Credits + +### Core Projects + +| Project | Maintainer | Role | +|:--------|:-----------|:-----| +| WSA Builds | [MustardChef/WSABuilds](https://github.com/MustardChef/WSABuilds) | Provides pre-built WSA archives | +| MindTheGapps | [MindTheGapps](https://mindthegapps.com) | Provides Google Apps package | +| Flet | [Flet](https://flet.dev) | Cross-platform UI framework | +| Nuitka | [Nuitka](https://nuitka.net) | Python to C compiler | +| PyInstaller | [PyInstaller](https://pyinstaller.org) | Application bundler | +| NSIS | [NSIS](https://nsis.sourceforge.io) | Windows installer system | + +### Acknowledgments + +- **[Microsoft](https://www.microsoft.com)** — For developing and maintaining Windows Subsystem for Android +- **[WSABuilds Community](https://github.com/MustardChef/WSABuilds)** — For providing nightly WSA builds +- **[MindTheGapps Team](https://mindthegapps.com)** — For maintaining the GApps package +- All open-source contributors whose work made this project possible + +--- + +## License + +This project is licensed under the **MIT License** — see [LICENSE](LICENSE) for details. + +--- + +
+ +### Links + +[![YouTube](https://img.shields.io/badge/YouTube-AT_Tech_Zone-red?style=for-the-badge&logo=youtube)](https://www.youtube.com/@AT_Tech_Zone) +[![Buy Me a Coffee](https://img.shields.io/badge/Buy_Me_a_Coffee-donate-yellow?style=for-the-badge&logo=buy-me-a-coffee)](https://buymeacoffee.com/mrcyberdev) +[![GitHub](https://img.shields.io/badge/GitHub-Organization-1B72C0?style=for-the-badge&logo=github)](https://github.com/WSA-Installer) + +--- + +*Built with care by AT Tech Zone — v1.2.0.0* + +
diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..54e2322 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,101 @@ +# Roadmap + +This document outlines the planned features and improvements for WSA Installer. + +## Current Release: v1.2.x + +**Status:** Active development and maintenance + +### Completed + +- [x] One-click WSA installation +- [x] Play Store integration (MindTheGapps 13.0) +- [x] Background service (`WSABackgroundService`) +- [x] Self-update system with parallel downloads +- [x] Repair and uninstall flows +- [x] File sharing via WebDAV +- [x] Glass transparency UI +- [x] Remote configuration via Rust gateway +- [x] NSIS professional installer +- [x] ADB authorization automation +- [x] WSAPatch for Windows 10 compatibility +- [x] Single-instance enforcement +- [x] Activity logging + +## Planned: v1.3.0 + +**Target:** Q3 2026 + +### Features + +- [ ] WSA version manager (install/switch between versions) +- [ ] Custom GApps selection (NikGapps, FlameGapps, MindTheGapps) +- [ ] WSA settings backup and restore +- [ ] ADB shell integration in UI +- [ ] Performance monitoring dashboard +- [ ] Automatic Hyper-V configuration wizard + +### Improvements + +- [ ] Improved download speeds with additional CDN sources +- [ ] Better error messages and recovery suggestions +- [ ] Enhanced glass transparency with blur effects +- [ ] Progress notification in Windows Action Center + +## Planned: v1.4.0 + +**Target:** Q4 2026 + +### Features + +- [ ] WSA app data export/import +- [ ] Multi-language support (i18n) +- [ ] Dark/light theme toggle +- [ ] Command-line batch operations +- [ ] WSA snapshot and restore +- [ ] Custom ADB port configuration + +### Infrastructure + +- [ ] MSI installer alternative +- [ ] Winget package +- [ ] Chocolatey package +- [ ] Scoop package +- [ ] Automated CI/CD pipeline + +## Planned: v2.0.0 + +**Target:** 2027 + +### Major Features + +- [ ] Complete UI redesign with Fluent Design +- [ ] Plugin system for custom integrations +- [ ] WSA marketplace integration +- [ ] Cross-platform support (Linux, macOS) +- [ ] WSA container management +- [ ] Enterprise deployment tools + +## Long-Term Vision + +- Become the definitive tool for WSA management +- Support all future WSA versions and Windows updates +- Build a community-driven plugin ecosystem +- Provide enterprise-grade deployment and management tools +- Maintain compatibility with new Android versions + +## How to Contribute + +We welcome contributions to help实现 these features! See our [Contributing Guide](CONTRIBUTING.md) for details. + +### Priority Areas + +1. **Testing** — Help us test on different hardware configurations +2. **Documentation** — Improve guides and troubleshooting +3. **Localization** — Translate to other languages +4. **Bug Reports** — Report and help fix issues +5. **Feature Development** — Implement planned features + +## Feedback + +Have ideas for the roadmap? Open a [Discussion](https://github.com/WSA-Installer/wsa-installer/discussions) or vote on existing [Feature Requests](https://github.com/WSA-Installer/wsa-installer/issues?q=label%3Aenhancement). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..7ea88d9 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,87 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability within WSA Installer, please send an email to the project maintainers. All security vulnerabilities will be promptly addressed. + +**Please do NOT report security vulnerabilities through public GitHub issues.** + +### What to Include + +When reporting a vulnerability, please include: + +- Description of the vulnerability +- Steps to reproduce +- Potential impact +- Suggested fix (if any) + +### Response Timeline + +- **Acknowledgment**: Within 48 hours +- **Initial assessment**: Within 1 week +- **Fix and release**: Depends on severity, typically within 2 weeks + +## Security Architecture + +WSA Installer implements multiple security layers: + +### Layer 1: Rust Security Gateway (`widget_ui.pyd`) + +- Zero-trust configuration parsing +- Signature verification for remote config +- Encrypted configuration handling +- Hash-based deduplication to prevent redundant updates + +### Layer 2: Instance Enforcement + +- Socket-based single instance lock prevents multiple installer copies +- Port-based process detection for conflict resolution + +### Layer 3: Windows Service + +- `WSABackgroundService` runs as SYSTEM-level Windows Service +- Auto-restart on failure with configurable retry logic +- User session process spawning via `CreateProcessAsUserW` + +### Layer 4: Source Protection + +- Nuitka compilation (`app.py` → `app.pyd`) for source code protection +- PyInstaller bundling with binary obfuscation +- Embedded Python 3.14 runtime isolation + +### Layer 5: Privilege Management + +- UAC elevation for system modifications +- Administrator privilege validation before operations +- Input blocking during sensitive automation sequences + +## Best Practices for Users + +1. **Download only from official sources** — Use the official GitHub releases +2. **Run as administrator** — Required for WSA installation and system modifications +3. **Keep updated** — Use the built-in self-update feature +4. **Verify checksums** — Compare downloaded file hashes when possible +5. **Review logs** — Check `wsa_activity.log` for suspicious activity + +## Security Updates + +Security updates will be released as patches to the current version. Users are encouraged to enable automatic updates or check the [Releases](https://github.com/WSA-Installer/wsa-installer/releases) page regularly. + +## Scope + +This security policy applies to: + +- The WSA Installer application (`WSA Installer.exe`) +- The NSIS installer (`WSA_Installer_Setup.exe`) +- The background service (`WSABackgroundService`) +- The native modules (`widget_ui.pyd`, `playstore_patcher_mem.pyd`) + +It does NOT apply to: + +- Third-party software (ADB, Python, etc.) +- Windows Subsystem for Android itself +- Applications installed within WSA + +## Acknowledgments + +We appreciate the security research community and responsible disclosure of vulnerabilities. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..275db6e --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,85 @@ +# Support + +## Getting Help + +If you need help with WSA Installer, here are the available support channels: + +### Documentation + +- [Installation Guide](docs/installation.md) — Step-by-step installation instructions +- [Troubleshooting Guide](docs/troubleshooting.md) — Solutions to common issues +- [CLI Reference](docs/cli-reference.md) — Command-line options +- [Architecture Guide](docs/architecture.md) — Technical overview + +### Community Support + +| Channel | Link | Best For | +|:--------|:-----|:---------| +| GitHub Issues | [Report a Bug](https://github.com/WSA-Installer/wsa-installer/issues/new?template=bug_report.yml) | Bug reports and issues | +| GitHub Discussions | [Ask a Question](https://github.com/WSA-Installer/wsa-installer/discussions) | Questions and general help | +| YouTube | [@AT_Tech_Zone](https://www.youtube.com/@AT_Tech_Zone) | Video tutorials and guides | + +### Contact + +- **YouTube**: [@AT_Tech_Zone](https://www.youtube.com/@AT_Tech_Zone) +- **Buy Me a Coffee**: [mrcyberdev](https://buymeacoffee.com/mrcyberdev) + +## Frequently Asked Questions + +### General + +**Q: What is WSA Installer?** +A: WSA Installer is a tool that automates the installation of Windows Subsystem for Android (WSA) with Google Play Store on Windows 10 and Windows 11. + +**Q: Is WSA Installer free?** +A: Yes, WSA Installer is free and open-source under the MIT License. + +**Q: Does WSA Installer work on Windows 10?** +A: Yes, WSA Installer supports Windows 10 build 19041 and later. + +### Installation + +**Q: Do I need to be an administrator?** +A: Yes, WSA Installer requires administrator privileges to install WSA and configure Windows features. + +**Q: Can I install WSA without Play Store?** +A: Yes, the installer offers both options: WSA only or WSA with Play Store. + +**Q: How long does installation take?** +A: Installation typically takes 5-15 minutes depending on your internet speed and system performance. + +**Q: What is bundle.wsa?** +A: `bundle.wsa` is a pre-packaged archive containing WSA packages. It's optional — the installer can download packages directly from GitHub. + +### Troubleshooting + +**Q: Virtualization is not detected** +A: Enable Intel VT-x or AMD-V in your BIOS/UEFI settings. Check your motherboard documentation for instructions. + +**Q: WSA won't start after installation** +A: Try restarting your computer. If the issue persists, use the Repair feature from Windows Settings → Apps → WSA Installer → Modify → Repair. + +**Q: Play Store is not working** +A: Ensure Developer Mode is enabled in WSA Settings. Try disconnecting and reconnecting ADB. Check the installer logs for errors. + +**Q: How do I uninstall WSA?** +A: Use the WSA Installer's built-in uninstaller, or go to Windows Settings → Apps → WSA Installer → Uninstall. + +### Advanced + +**Q: Can I install multiple WSA versions?** +A: Not currently. This is a planned feature for a future release. + +**Q: How do I use the background service?** +A: The background service is installed automatically. It monitors WSA status and manages the Play Store SDK. You can manage it via Windows Services (`WSABackgroundService`). + +**Q: Can I use WSA Installer in enterprise environments?** +A: Yes, WSA Installer supports silent installation via `/S` flag, making it suitable for enterprise deployment. + +## Feature Requests + +Have an idea for a new feature? [Open a feature request](https://github.com/WSA-Installer/wsa-installer/issues/new?template=feature_request.yml) on GitHub. + +## Contributing + +Want to help improve WSA Installer? See our [Contributing Guide](CONTRIBUTING.md) for details. diff --git a/assets/favicon.svg b/assets/favicon.svg new file mode 100644 index 0000000..ee6cbb0 --- /dev/null +++ b/assets/favicon.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + WSA + diff --git a/assets/logo-dark.svg b/assets/logo-dark.svg new file mode 100644 index 0000000..0600de2 --- /dev/null +++ b/assets/logo-dark.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + WSA + diff --git a/assets/logo-light.svg b/assets/logo-light.svg new file mode 100644 index 0000000..1c0c393 --- /dev/null +++ b/assets/logo-light.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + WSA + diff --git a/assets/logo.svg b/assets/logo.svg new file mode 100644 index 0000000..c66ca21 --- /dev/null +++ b/assets/logo.svg @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WSA + diff --git a/docs/adb.md b/docs/adb.md new file mode 100644 index 0000000..c51c04d --- /dev/null +++ b/docs/adb.md @@ -0,0 +1,165 @@ +# ADB Reference + +ADB (Android Debug Bridge) is used by WSA Installer to communicate with WSA for Play Store installation and management. + +## ADB in WSA Installer + +WSA Installer automates ADB operations for: + +- Connecting to WSA +- Authorizing USB debugging +- Installing Play Store (GApps) +- Verifying package installation +- Managing WSA developer options + +## ADB Connection + +### Port + +WSA exposes ADB on port **58526** by default. + +### Connect Command + +```cmd +adb connect 127.0.0.1:58526 +``` + +### Connection Process + +WSA Installer automatically: + +1. Checks if WSA is running +2. Probes port 58526 +3. Connects via ADB +4. Handles authorization (if needed) + +## ADB Authorization + +When connecting to WSA for the first time, you'll see an "Allow USB debugging" popup. + +### Automatic Authorization + +WSA Installer automates this process using `pywinauto`: + +1. Detects the "Allow USB debugging" window +2. Clicks "Always allow from this computer" +3. Clicks "Allow" + +### Manual Authorization + +If automatic authorization fails: + +1. Check the WSA window for the popup +2. Check "Always allow from this computer" +3. Click "Allow" + +## Common ADB Commands + +### Check Connected Devices + +```cmd +adb devices +``` + +### Install APK + +```cmd +adb install -r package.apk +``` + +### Uninstall Package + +```cmd +adb uninstall com.package.name +``` + +### List Installed Packages + +```cmd +adb shell pm list packages +``` + +### Check Specific Package + +```cmd +adb shell pm list packages com.android.vending +``` + +### Start Activity + +```cmd +adb shell am start -n com.package/.Activity +``` + +### Send Broadcast + +```cmd +adb shell am broadcast -a com.action.NAME +``` + +## Troubleshooting ADB + +### "Device unauthorized" + +1. Check the WSA window for the authorization popup +2. Enable Developer Mode in WSA Settings +3. Disconnect and reconnect ADB: + ```cmd + adb disconnect + adb connect 127.0.0.1:58526 + ``` + +### "Connection refused" + +1. Ensure WSA is running +2. Check that Developer Mode is enabled +3. Restart WSA: + ```cmd + taskkill /F /IM WsaClient.exe + wsa://system + ``` +4. Wait 30 seconds, then retry + +### "Device offline" + +1. Disconnect ADB: `adb disconnect` +2. Kill ADB server: `adb kill-server` +3. Restart ADB server: `adb start-server` +4. Reconnect: `adb connect 127.0.0.1:58526` + +### Port Changed + +If WSA uses a different port: + +1. Check WSA Settings → Developer → Wireless debugging +2. Note the port number +3. Connect with the correct port: + ```cmd + adb connect 127.0.0.1:PORT_NUMBER + ``` + +### Multiple ADB Instances + +If you have multiple ADB installations: + +1. Use the full path to the WSA Installer's ADB: + ``` + assets\adb.exe connect 127.0.0.1:58526 + ``` + +## ADB in WSA WebDev + +The WSA WebDev project uses ADB for server control: + +```bash +# Start WebDAV server +adb shell am broadcast -a com.wsa.webdav.START + +# Stop WebDAV server +adb shell am broadcast -a com.wsa.webdav.STOP + +# Check status +adb shell am broadcast -a com.wsa.webdav.STATUS +``` + +See the [WebDAV documentation](webdav.md) for details. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..0d645b4 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,301 @@ +# Architecture Guide + +This document describes the technical architecture of WSA Installer. + +## System Overview + +WSA Installer is a Python-based application with Rust native modules, designed to automate WSA installation and management on Windows. + +``` +┌──────────────────────────────────────────────────────────────┐ +│ WSA Installer v1.2.0 │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌──────────────────┐ ┌────────────┐ │ +│ │ Flet GUI │ │ InstallerLogic │ │ Remote │ │ +│ │ (UI Layer) │◄──►│ (Core Engine) │◄──►│ Config │ │ +│ └──────┬──────┘ └────────┬─────────┘ └────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌─────────────┐ ┌──────────────────┐ │ +│ │ 5-Step │ │ Rust Native │ │ +│ │ Wizard │ │ Modules (.pyd) │ │ +│ │ Pages │ └──────────────────┘ │ +│ └─────────────┘ │ │ +│ ▼ │ +│ ┌─────────────┐ ┌──────────────────┐ ┌────────────┐ │ +│ │ Embedded │ │ Windows Service │ │ NSIS │ │ +│ │ Python 3.14│ │ (Background) │ │ Installer │ │ +│ └─────────────┘ └──────────────────┘ └────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────┘ +``` + +## Core Components + +### 1. Flet GUI (UI Layer) + +**File:** `app.py` — `main()` function (lines 6936-9044) + +The GUI is built with Flet, a cross-platform UI framework. It provides: + +- 5-step wizard interface +- Sidebar navigation +- Glass transparency (configurable alpha) +- Animated transitions +- Overlay dialogs + +**Key Elements:** +- `ft.Stack` — Root container with overlays +- `title_bar` — Custom frameless window drag area +- `sidebar` — Step navigation with status indicators +- `content_area` — Dynamic content pages +- `bottom_bar` — Navigation buttons + +### 2. InstallerLogic (Core Engine) + +**File:** `app.py` — `InstallerLogic` class (lines 2431-5995) + +The core engine handles all installation operations: + +**Methods:** +- `download_asset()` — Parallel chunked download with resume +- `extract_7z()` — 7z archive extraction +- `install_wsa()` — 6-phase WSA installation +- `add_playStore()` — 7-phase Play Store integration +- `uninstall_wsa_logic()` — Complete WSA removal +- `_adb_connect_loop()` — ADB connection management +- `_automate_adb_authorization()` — UI automation for ADB popup + +**State Dictionary:** +Contains 40+ keys tracking wizard state, progress, and UI updates. + +### 3. ConfigController + +**File:** `app.py` — `ConfigController` class (lines 1603-2036) + +Manages application configuration with source tracking: + +``` +Default Config → Dev Mode Config → Server Config +``` + +**Features:** +- Source-tracked values +- Validation against allowed types/values +- Server-side updates via RemoteConfigManager + +### 4. RemoteConfigManager + +**File:** `app.py` — `RemoteConfigManager` class (lines 2154-2286) + +Fetches and applies remote configuration: + +**Process:** +1. Polls server JSON via `widget_ui.pyd` +2. Validates signature via Rust gateway +3. Applies configuration changes +4. Hash-based deduplication + +### 5. Background Service + +**File:** `app.py` — `WSABackgroundService` (lines 777-1598) + +Windows Service running in SYSTEM context: + +**Capabilities:** +- WSA port monitoring (58526) +- SDK lifecycle management +- User session process spawning via `CreateProcessAsUserW` +- Auto-restart on failure + +### 6. Native Modules + +| Module | Language | Purpose | +|:-------|:---------|:--------| +| `widget_ui.pyd` | Rust | Zero-trust config gateway | +| `playstore_patcher_mem.pyd` | Rust | Play Store patcher SDK | + +## Security Architecture + +``` +┌──────────────────────────────────────────────────────┐ +│ Security Layers │ +├──────────────────────────────────────────────────────┤ +│ │ +│ Layer 1: widget_ui.pyd (Rust) │ +│ ├── Zero-trust config gateway │ +│ ├── Signature verification │ +│ └── Encrypted config parsing │ +│ │ +│ Layer 2: Socket-based Instance Locks │ +│ ├── Single instance enforcement │ +│ └── Port-based process detection │ +│ │ +│ Layer 3: Windows Service │ +│ ├── SYSTEM-level service │ +│ ├── Auto-restart on failure │ +│ └── User session process spawning │ +│ │ +│ Layer 4: Source Protection │ +│ ├── Nuitka compilation │ +│ ├── PyInstaller bundling │ +│ └── Binary string obfuscation │ +│ │ +└──────────────────────────────────────────────────────┘ +``` + +## Build Pipeline + +### Primary Build (build.bat) + +``` +Step 1: Clean + └── Removes dist/, build/, app.pyd + +Step 2: Dependencies + └── pip install -r requirements.txt + +Step 3: Version Update + └── PowerShell replaces version in app.py + file_version_info.txt + +Step 4: Nuitka Module + ├── Compiles app.py → app.pyd (source protection) + └── Renames app.py → wsa.py to hide source + +Step 5: PyInstaller Onedir + ├── Uses WSA_Installer_Download_onedir.spec + └── Restores app.py from wsa.py + +Step 6: WSARepair.exe + └── PyInstaller --onefile + +Step 7: Flet Client Patch + ├── Patches flet.exe icon + version info + └── Creates patched flet-windows.zip + +Step 8: NSIS Installer + └── Builds WSA_Installer_Setup.exe +``` + +## Data Flow + +### Installation Flow + +```mermaid +sequenceDiagram + participant User + participant GUI as Flet GUI + participant IL as InstallerLogic + participant DL as Download Manager + participant EXT as Extractor + participant WSA as WSA + participant ADB as ADB + + User->>GUI: Click Install + GUI->>IL: start_install() + IL->>DL: download_asset() + DL-->>GUI: progress updates + DL->>EXT: extract_7z() + EXT->>WSA: install_wsa() + WSA-->>IL: installation complete + IL->>ADB: add_playStore() + ADB-->>IL: Play Store installed + IL-->>GUI: step complete +``` + +### Configuration Flow + +```mermaid +sequenceDiagram + participant App as Application + participant CC as ConfigController + participant RCM as RemoteConfigManager + participant WU as widget_ui.pyd + participant Server as Config Server + + App->>CC: load_config() + CC->>RCM: fetch() + RCM->>WU: load() + WU->>Server: HTTPS GET + Server-->>WU: JSON config + WU-->>RCM: validated config + RCM->>CC: apply() + CC-->>App: config updated +``` + +## File Structure + +``` +wsa-installer/ +├── app.py # Main application (~11K lines) +├── run.py # Entry point +├── WSARepair.py # Windows Settings proxy +├── patch_flet.py # Flet client patcher +├── launcher.cs # C# launcher +│ +├── assets/ # Runtime resources +│ ├── adb.exe # ADB binary +│ ├── AppxManifest.xml # WSA manifest +│ ├── Run.bat # MagiskOnWSALocal launcher +│ ├── settings.dat # Pre-patched WSA settings +│ ├── WsaClient.exe # Patched WSA client +│ └── icons/ # Application icons +│ +├── native/ # Rust native modules +│ ├── widget_ui.pyd # Security gateway +│ └── playstore_patcher_mem.pyd # Play Store SDK +│ +├── emb_py/ # Embedded Python 3.14 +│ ├── python/ # CPython runtime +│ ├── PySide6/ # Qt6 bindings +│ └── requests/ # HTTP client +│ +├── build/ # Build scripts +│ ├── build.bat # Primary build +│ ├── build2.bat # Alternate build +│ └── WSA_Installer_Setup.nsi # NSIS script +│ +├── docs/ # Documentation +└── tests/ # Tests +``` + +## Performance Optimizations + +### Parallel Downloads + +- 30-chunk parallel download system +- HTTP Range headers for resume support +- Thread pool executor for concurrent requests + +### Caching + +- Download cache in `out_asset/cache/` +- Bundle detection avoids re-downloads +- Config hash deduplication + +### Memory Management + +- Streaming subprocess output +- Queue-based thread communication +- Lazy loading of heavy components + +## Error Recovery + +### Retry Logic + +- ADB connection: 15 attempts with server restart +- Download resume: Partial file preservation +- Process kill: 3-attempt retry loops + +### Fallback Mechanisms + +- `CreateProcessAsUserW` → `Popen` fallback +- Server config → default config fallback +- Bundle → GitHub download fallback + +### Logging + +- Activity log: `wsa_activity.log` +- Debug log: `debug.log` +- UI log box in all dialogs diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..c3ef5c2 --- /dev/null +++ b/docs/cli-reference.md @@ -0,0 +1,158 @@ +# CLI Reference + +WSA Installer supports various command-line arguments for automation and advanced usage. + +## Basic Usage + +```cmd +WSA Installer.exe [OPTIONS] +``` + +## Command Line Arguments + +| Argument | Description | +|:---------|:------------| +| `--install-service` | Install WSABackgroundService | +| `--uninstall-service` | Remove WSABackgroundService | +| `--bg-service` | Run as background service (SYSTEM context) | +| `--bg-service-gui` | Background service with visible console | +| `--uninstall` | Launch uninstall dialog | +| `--update ` | Self-update dialog | +| `--repair-wsa` | 4-step WSA repair | +| `--file-sharing` | File sharing (WebDAV mount) dialog | +| `--file-sharing root` | File sharing with root access | +| `--ad ` | Spawn ad overlay | +| `--sdk` | Start Play Store patcher SDK | + +## NSIS Installer Arguments + +| Argument | Description | +|:---------|:------------| +| `/S` | Silent installation | +| `/S /repair` | Silent repair from Windows Settings | + +## Examples + +### Silent Installation + +```cmd +WSA_Installer_Setup.exe /S +``` + +Installs WSA Installer to `C:\Program Files\WSA Installer` without showing any UI. + +### Install Background Service + +```cmd +WSA Installer.exe --install-service +``` + +Creates and starts the `WSABackgroundService` Windows service. + +### Uninstall Background Service + +```cmd +WSA Installer.exe --uninstall-service +``` + +Stops and removes the `WSABackgroundService`. + +### Launch Uninstaller + +```cmd +WSA Installer.exe --uninstall +``` + +Opens the uninstall wizard with 7-step visual progress. + +### Repair WSA + +```cmd +WSA Installer.exe --repair-wsa +``` + +Opens the 4-step repair wizard (detect → stop → backup → reinstall). + +### File Sharing (User Mode) + +```cmd +WSA Installer.exe --file-sharing +``` + +Opens the file sharing setup dialog for user storage access. + +### File Sharing (Root Mode) + +```cmd +WSA Installer.exe --file-sharing root +``` + +Opens the file sharing setup dialog with root filesystem access. + +### Self-Update + +```cmd +WSA Installer.exe --update https://example.com/new.exe 1.3.0 +``` + +Downloads and installs the specified update version. + +### Background Service Mode + +```cmd +WSA Installer.exe --bg-service +``` + +Runs as a Windows Service in SYSTEM context (no GUI). + +### Background Service with GUI + +```cmd +WSA Installer.exe --bg-service-gui +``` + +Runs as background service with a visible console window for debugging. + +## Windows Service Management + +### Using sc Commands + +```cmd +# Install service +sc create WSABackgroundService binPath= "C:\Program Files\WSA Installer\WSA Installer.exe --bg-service" start= auto + +# Configure failure recovery +sc failure WSABackgroundService reset=86400 actions=restart/10000/restart/15000/restart/30000 + +# Start service +sc start WSABackgroundService + +# Stop service +sc stop WSABackgroundService + +# Delete service +sc delete WSABackgroundService +``` + +### Service Properties + +| Property | Value | +|:---------|:------| +| Name | WSABackgroundService | +| Display Name | WSA Background Service | +| Start Type | Automatic | +| Recovery | Restart after 10s, 15s, 30s | +| Reset Period | 86400 seconds (24 hours) | + +## Environment Variables + +| Variable | Description | +|:---------|:------------| +| `FLET_VIEW_PATH` | Custom path to Flet client executable | + +## Exit Codes + +| Code | Description | +|:-----|:------------| +| 0 | Success | +| 1 | Error or cancellation | diff --git a/docs/developer-guide.md b/docs/developer-guide.md new file mode 100644 index 0000000..72cf660 --- /dev/null +++ b/docs/developer-guide.md @@ -0,0 +1,211 @@ +# Developer Guide + +This guide is for developers who want to contribute to WSA Installer or understand its internals. + +## Prerequisites + +- Python 3.14 +- Windows 10/11 +- Git +- Administrator privileges (for testing) + +## Getting Started + +### Clone the Repository + +```bash +git clone https://github.com/WSA-Installer/wsa-installer.git +cd wsa-installer +``` + +### Set Up Development Environment + +```bash +# Run the development launcher +run.bat +``` + +This will: +1. Create a Python virtual environment +2. Install all dependencies +3. Launch the application + +### Manual Setup + +```bash +# Create virtual environment +python -m venv venv + +# Activate it +venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt + +# Run the application +python run.py +``` + +## Project Structure + +``` +wsa-installer/ +├── app.py # Main application (~11K lines) +├── run.py # Entry point: import app; app.start() +├── WSARepair.py # Windows Settings proxy +├── patch_flet.py # Flet client patcher +├── launcher.cs # C# launcher for Nuitka builds +│ +├── assets/ # Runtime resources +│ ├── adb.exe # ADB binary +│ ├── AppxManifest.xml # WSA manifest +│ ├── Run.bat # MagiskOnWSALocal launcher +│ ├── settings.dat # Pre-patched WSA settings +│ └── icons/ # Application icons +│ +├── native/ # Rust native modules +│ ├── widget_ui.pyd # Security gateway +│ └── playstore_patcher_mem.pyd # Play Store SDK +│ +├── emb_py/ # Embedded Python 3.14 +├── build/ # Build scripts +├── docs/ # Documentation +└── tests/ # Tests +``` + +## Key Files + +### app.py + +The main application file containing: + +- **Flet GUI** (lines 6936-9044) — User interface +- **InstallerLogic** (lines 2431-5995) — Core engine +- **ConfigController** (lines 1603-2036) — Configuration management +- **RemoteConfigManager** (lines 2154-2286) — Server sync +- **Background Service** (lines 777-1598) — Windows SCM service +- **Dialog Functions** (lines 9052-10993) — Uninstall, update, repair, file sharing + +### run.py + +Simple entry point: +```python +import app +app.start() +``` + +### WSARepair.py + +Proxy for Windows Settings Repair/Uninstall buttons. Finds the installer via 4 registry search methods. + +## Code Conventions + +### Python Style + +- Follow PEP 8 +- Use meaningful variable names +- Add docstrings for public functions +- Type hints where appropriate + +### Commit Messages + +Follow Conventional Commits: +``` +feat(scope): description +fix(scope): description +docs(scope): description +``` + +### Branch Naming + +- `feature/description` — New features +- `fix/description` — Bug fixes +- `docs/description` — Documentation + +## Building + +### Primary Build + +```cmd +build.bat +``` + +Produces `dist/WSA_Installer_Setup.exe`. + +### Build Requirements + +- Python 3.14 with pip +- Nuitka: `pip install nuitka` +- PyInstaller: `pip install pyinstaller` +- NSIS: [nsis.sourceforge.io](https://nsis.sourceforge.io) + +### Build Pipeline + +1. Clean previous builds +2. Install dependencies +3. Update version numbers +4. Nuitka: Compile `app.py` → `app.pyd` +5. PyInstaller: Bundle to `dist/WSA Installer/` +6. Patch Flet client +7. NSIS: Build installer + +## Testing + +### Manual Testing + +1. Run the application: `run.bat` +2. Test each wizard step +3. Test repair and uninstall flows +4. Test on both Windows 10 and 11 + +### Test Checklist + +- [ ] Fresh installation works +- [ ] Play Store installs correctly +- [ ] Repair flow completes +- [ ] Uninstall removes everything +- [ ] Background service starts +- [ ] File sharing mounts drive +- [ ] Self-update works +- [ ] UI renders correctly + +## Debugging + +### Enable Debug Logging + +Edit `app.py` and set debug flags: + +```python +DEBUG = True +``` + +### View Logs + +- `wsa_activity.log` — Session activity +- `debug.log` — Debug output +- UI Log Box — In-app logging + +### Common Debug Scenarios + +**Download issues:** +- Check network connectivity +- Verify GitHub releases are accessible +- Check download progress in UI + +**ADB issues:** +- Ensure WSA is running +- Check Developer Mode is enabled +- Verify port 58526 is accessible + +**Service issues:** +- Check Windows Event Viewer +- Verify service permissions +- Review service failure recovery + +## Contributing + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines. + +## Architecture + +See [architecture.md](architecture.md) for detailed architecture documentation. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..cca2a0e --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,157 @@ +# Installation Guide + +This guide walks you through installing WSA Installer on your Windows 10 or Windows 11 system. + +## Prerequisites + +| Requirement | Minimum | Recommended | +|:------------|:--------|:------------| +| OS | Windows 10 (build 19041+) or Windows 11 | Windows 11 22H2+ | +| RAM | 8 GB | 16 GB | +| Disk Space | 10 GB free | SSD with 20 GB free | +| Internet | Required for initial download | Broadband recommended | +| Privileges | Administrator | Administrator | +| Virtualization | Enabled in BIOS/UEFI | Intel VT-x or AMD-V | + +### Windows Features Required + +The following Windows features must be enabled. WSA Installer can enable them automatically: + +- **Hyper-V** — Microsoft's hardware virtualization +- **VirtualMachinePlatform** — Required for WSA +- **HypervisorPlatform** — Hypervisor interface +- **Windows Subsystem for Linux** — Required for WSA + +## Download + +### Option A: Installer Only + +Download `WSA_Installer_Setup.exe` (~228 MB) from the [latest release](https://github.com/WSA-Installer/wsa-installer/releases/latest). + +The installer will download WSA packages directly from GitHub during installation. + +### Option B: Installer + Bundle + +Download both: +1. `WSA_Installer_Setup.exe` (~228 MB) +2. `bundle.wsa` (~1.21 GB) + +Place both files in the same folder. The installer will detect the bundle automatically. + +## Installation Steps + +### Step 1: Run the Installer + +1. Right-click `WSA_Installer_Setup.exe` +2. Select **Run as administrator** +3. Accept the UAC (User Account Control) prompt + +### Step 2: Welcome Screen + +The installer will display a welcome page with information about the installation process. Click **Next** to continue. + +### Step 3: System Check + +The installer automatically scans your system for: + +- Virtualization support (VT-x/AMD-V) +- Hyper-V status +- VirtualMachinePlatform status +- HypervisorPlatform status +- WSL status + +If any required features are missing, the installer will offer to enable them. You may need to restart your computer after enabling features. + +### Step 4: Install WSA + +The installer proceeds through 6 phases: + +| Phase | Description | +|:------|:------------| +| 1. Locate Package | Finds WSA package (from bundle or GitHub download) | +| 2. Verify Assets | Validates archive integrity | +| 3. Prepare System | Extracts files, copies to installation directory | +| 4. Apply Patches | Developer Mode settings, registry fixes, WsaClient patches | +| 5. Register Package | Registers WSA with Windows | +| 6. Finalize | Creates shortcuts, configures background service | + +### Step 5: Add Play Store (Optional) + +If you selected the Play Store option, the installer proceeds through 7 additional phases: + +| Phase | Description | +|:------|:------------| +| 1. Prerequisites | Checks WSA is running and Developer Mode is enabled | +| 2. Enable Dev Mode | Patches settings.dat for Developer Mode | +| 3. Connect ADB | Establishes ADB connection to WSA | +| 4. Prepare Package | Locates and verifies GApps package | +| 5. Apply Patches | Merges Play Store files into WSA | +| 6. Run Installer | Executes Run.bat via ADB | +| 7. Finalize | Verifies Play Store, cleans up, restarts WSA | + +### Step 6: Complete + +Once installation is complete: + +- **Play Store** shortcut appears in Start Menu +- **Windows Subsystem for Android** shortcut appears on Desktop +- **WSABackgroundService** is installed and running +- You can now launch Android apps directly from the Start Menu + +## Silent Installation + +For automated deployment: + +```cmd +WSA_Installer_Setup.exe /S +``` + +The silent installer: +- Installs to `C:\Program Files\WSA Installer` +- Registers the Windows service +- Creates desktop and Start Menu shortcuts +- Does NOT show any UI + +## Post-Installation + +### Verify WSA is Working + +1. Open the Start Menu +2. Search for "Windows Subsystem for Android" +3. Launch the WSA Settings app +4. Enable Developer Mode if not already enabled + +### Verify Play Store + +1. Open the Start Menu +2. Search for "Play Store" +3. Sign in with your Google account +4. Install Android apps + +### Check Background Service + +1. Open Windows Services (`services.msc`) +2. Find `WSABackgroundService` +3. Verify it's running + +## Troubleshooting + +### Installation Fails + +1. Ensure you're running as administrator +2. Check that virtualization is enabled in BIOS/UEFI +3. Try enabling Hyper-V manually: `dism.exe /Online /Enable-Feature /FeatureName:Microsoft-Hyper-V /All` + +### WSA Won't Start + +1. Restart your computer after installation +2. Check that all Windows features are enabled +3. Run the installer again and use the Repair option + +### Play Store Not Working + +1. Ensure Developer Mode is enabled in WSA Settings +2. Wait a few minutes for Play Store to initialize +3. Try signing out and back into your Google account + +For more troubleshooting, see the [Troubleshooting Guide](troubleshooting.md). diff --git a/docs/repair.md b/docs/repair.md new file mode 100644 index 0000000..c613f0e --- /dev/null +++ b/docs/repair.md @@ -0,0 +1,132 @@ +# Repair Guide + +WSA Installer includes a built-in repair feature that can fix common WSA issues without requiring a complete reinstall. + +## When to Use Repair + +Use the repair feature when: + +- WSA won't start +- WSA crashes frequently +- Play Store is not working +- WSA settings are corrupted +- After a Windows update breaks WSA +- Background service is not running + +## How to Repair + +### Method 1: From Windows Settings + +1. Open **Settings** → **Apps** → **Installed apps** +2. Find **WSA Installer** in the list +3. Click the three dots (**) → **Modify** +4. Select **Repair / Reinstall** +5. Follow the repair wizard + +### Method 2: From WSA Installer + +1. Open WSA Installer +2. Click **Advanced** in the sidebar +3. Click **Repair WSA** button +4. Follow the repair wizard + +### Method 3: Command Line + +```cmd +WSA_Installer.exe --repair-wsa +``` + +## Repair Process + +The repair wizard performs 4 steps: + +### Step 1: Detect WSA + +The installer runs `Get-AppxPackage` via PowerShell to find the WSA installation location. If WSA is not found, the repair cannot proceed. + +### Step 2: Stop WSA Processes + +All WSA-related processes are terminated: + +- `WsaClient.exe` +- `WsaSvc` +- `vmmem` +- `WsaService` +- `adb.exe` + +This ensures files are not locked during repair. + +### Step 3: Backup User Data + +Your WSA data (installed apps, settings) is backed up to a safe location. This backup is used to restore your data after reinstall. + +The backup includes: +- App data +- User settings +- Developer Mode configuration + +### Step 4: Reinstall WSA + +1. The existing WSA installation is removed +2. A fresh WSA installation is created +3. Your backed-up data is restored +4. Play Store is re-patched if previously installed +5. Background service is restarted + +## Backup Location + +Your WSA backup is stored at: + +``` +%LOCALAPPDATA%\WSA Installer\backup\ +``` + +### Restore from Backup + +If you need to manually restore from backup: + +1. Stop WSA: `taskkill /F /IM WsaClient.exe` +2. Copy the backup contents to the WSA data folder +3. Restart WSA + +## Repair vs Reinstall + +| Feature | Repair | Reinstall | +|:--------|:-------|:----------| +| Preserves app data | Yes | No | +| Preserves Play Store | Yes | No | +| Fixes corrupted files | Yes | Yes | +| Time required | 2-5 minutes | 10-15 minutes | +| Requires re-download | No | Yes | + +## Troubleshooting Repair + +### Repair Fails + +1. Try running as administrator +2. Ensure no other WSA processes are running +3. Check that you have enough disk space +4. Try the manual kill steps below, then retry repair + +### Manual WSA Kill + +If WSA won't stop: + +```cmd +taskkill /F /IM WsaService.exe +taskkill /F /IM WsaClient.exe +taskkill /F /IM WsaSettings.exe +``` + +### Backup Corrupted + +If the backup is corrupted, the repair will skip the restore step. You'll need to reinstall your apps manually. + +### Repair Stuck + +If the repair process appears stuck: + +1. Wait 5 minutes — some operations take time +2. Check the log output in the UI +3. If still stuck, force-close and retry +4. As a last resort, use the full uninstall and reinstall diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..2e81cf1 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,344 @@ +# Troubleshooting Guide + +This guide covers common issues and their solutions when using WSA Installer. + +## Table of Contents + +- [Installation Issues](#installation-issues) +- [WSA Issues](#wsa-issues) +- [Play Store Issues](#play-store-issues) +- [Background Service Issues](#background-service-issues) +- [File Sharing Issues](#file-sharing-issues) +- [Update Issues](#update-issues) +- [UI Issues](#ui-issues) + +--- + +## Installation Issues + +### "Virtualization not detected" + +**Symptoms:** The system check fails to detect virtualization support. + +**Solutions:** + +1. **Enable in BIOS/UEFI:** + - Restart your computer + - Enter BIOS/UEFI (usually F2, F10, or Del) + - Find "Virtualization Technology" or "Intel VT-x" / "AMD-V" + - Enable it + - Save and exit + +2. **Check Windows Features:** + ```cmd + dism /online /get-features /format:table | findstr Hyper + ``` + +3. **Enable Hyper-V:** + ```cmd + dism.exe /Online /Enable-Feature /FeatureName:Microsoft-Hyper-V /All + ``` + +### "Hyper-V won't enable" + +**Solutions:** + +1. Check if WSL2 is installed: + ```cmd + wsl --status + ``` + +2. Set hypervisor launch type: + ```cmd + bcdedit /set hypervisorlaunchtype auto + ``` + +3. Restart your computer + +### "Installation fails with error" + +**Solutions:** + +1. Run as administrator +2. Check available disk space (10 GB minimum) +3. Temporarily disable antivirus +4. Check Windows Event Viewer for errors + +### "Download fails or is slow" + +**Solutions:** + +1. Check internet connection +2. Try downloading `bundle.wsa` manually +3. Place `bundle.wsa` in the same folder as the installer +4. Check firewall settings + +--- + +## WSA Issues + +### "WSA won't start" + +**Solutions:** + +1. Restart your computer +2. Check Windows Features are enabled +3. Run the installer's Repair feature +4. Manually start WSA: + ```cmd + wsa://system + ``` + +### "WSA crashes immediately" + +**Solutions:** + +1. Check for Windows updates +2. Run the installer's Repair feature +3. Clear WSA data: + - Settings → Apps → WSA → Advanced options → Reset +4. Reinstall WSA + +### "WSA is very slow" + +**Solutions:** + +1. Ensure you have enough RAM (8 GB minimum, 16 GB recommended) +2. Close unnecessary applications +3. Use an SSD instead of HDD +4. Check Task Manager for resource usage + +### "WSA settings won't open" + +**Solutions:** + +1. Try: `wsa://settings` +2. Restart WSA: `taskkill /F /IM WsaClient.exe` +3. Run the installer's Repair feature + +### "Developer Mode is disabled" + +**Solutions:** + +1. Open WSA Settings +2. Go to Developer tab +3. Enable Developer Mode +4. If the toggle won't stick, the installer can patch `settings.dat` + +--- + +## Play Store Issues + +### "Play Store not appearing" + +**Solutions:** + +1. Ensure you selected "Add Play Store" during installation +2. Check if the Play Store package is installed: + ```cmd + adb shell pm list packages com.android.vending + ``` +3. Run the installer's Repair feature and re-add Play Store + +### "Play Store won't open" + +**Solutions:** + +1. Clear Play Store cache: + ```cmd + adb shell pm clear com.android.vending + ``` +2. Clear Google Play Services cache: + ```cmd + adb shell pm clear com.google.android.gms + ``` +3. Restart WSA + +### "Can't sign in to Google account" + +**Solutions:** + +1. Ensure date and time are correct +2. Check internet connection +3. Try a different Google account +4. Clear Google account data and retry + +### "Apps won't install from Play Store" + +**Solutions:** + +1. Check available storage in WSA +2. Clear Play Store cache +3. Check internet connection +4. Try installing a different app + +### "ADB authorization popup not appearing" + +**Solutions:** + +1. Ensure Developer Mode is enabled +2. Disconnect and reconnect ADB: + ```cmd + adb disconnect + adb connect 127.0.0.1:58526 + ``` +3. Manually check the WSA window for the popup + +--- + +## Background Service Issues + +### "Service won't start" + +**Solutions:** + +1. Run as administrator: + ```cmd + WSA Installer.exe --install-service + ``` + +2. Check service status: + ```cmd + sc query WSABackgroundService + ``` + +3. Check Windows Event Viewer for errors + +### "Service keeps restarting" + +**Solutions:** + +1. Check the service logs +2. Ensure WSA is installed correctly +3. Reinstall the service: + ```cmd + WSA Installer.exe --uninstall-service + WSA Installer.exe --install-service + ``` + +### "Service not monitoring WSA" + +**Solutions:** + +1. Ensure the service is running +2. Check that WSA is installed +3. Restart the service: + ```cmd + sc stop WSABackgroundService + sc start WSABackgroundService + ``` + +--- + +## File Sharing Issues + +### "Drive won't mount" + +**Solutions:** + +1. Ensure WSA is running +2. Check ADB connection: + ```cmd + adb devices + ``` +3. Verify WebDAV server is running: + ```cmd + curl http://127.0.0.1:8088 + ``` +4. Check WebClient service: + - Open `services.msc` + - Find "WebDAV Redirector" + - Ensure it's running + +### "Permission denied accessing drive" + +**Solutions:** + +1. Ensure you have the correct mode (User vs Root) +2. Check folder permissions in WSA +3. Try accessing a different folder + +### "Slow file transfer" + +**Solutions:** + +1. Use USB instead of WiFi for ADB +2. Transfer large files as a batch +3. Close other network-intensive applications + +### "Drive disconnects randomly" + +**Solutions:** + +1. Check network stability +2. Ensure WSA stays running +3. Disable power saving for USB devices +4. Check for conflicts with other network drives + +--- + +## Update Issues + +### "Update fails to download" + +**Solutions:** + +1. Check internet connection +2. Try downloading manually from GitHub Releases +3. Run the installer as administrator + +### "Update fails to install" + +**Solutions:** + +1. Run as administrator +2. Close all WSA Installer instances +3. Stop the background service temporarily +4. Try the manual update method + +--- + +## UI Issues + +### "Window is transparent/invisible" + +**Solutions:** + +1. Press Alt+Tab to find the window +2. Adjust the glass transparency slider +3. Check if the Flet client is properly patched + +### "Buttons not responding" + +**Solutions:** + +1. Wait a few seconds — the UI may be loading +2. Press Alt+F4 to close and restart +3. Check Task Manager for unresponsive processes + +### "UI looks broken or misaligned" + +**Solutions:** + +1. Check display scaling settings (100% recommended) +2. Update display drivers +3. Try a different display resolution + +--- + +## Getting More Help + +If your issue isn't covered here: + +1. Check the [GitHub Issues](https://github.com/WSA-Installer/wsa-installer/issues) for similar problems +2. Open a new [Bug Report](https://github.com/WSA-Installer/wsa-installer/issues/new?template=bug_report.yml) +3. Join the [GitHub Discussions](https://github.com/WSA-Installer/wsa-installer/discussions) +4. Watch video tutorials on [YouTube](https://www.youtube.com/@AT_Tech_Zone) + +## Log Files + +When reporting issues, include relevant logs: + +- **Activity Log:** `wsa_activity.log` +- **Debug Log:** `debug.log` +- **UI Log Box:** Available in all installer dialogs diff --git a/docs/uninstall.md b/docs/uninstall.md new file mode 100644 index 0000000..43344e5 --- /dev/null +++ b/docs/uninstall.md @@ -0,0 +1,144 @@ +# Uninstall Guide + +WSA Installer provides a complete uninstallation process that removes WSA, the background service, shortcuts, and registry entries. + +## How to Uninstall + +### Method 1: From Windows Settings + +1. Open **Settings** → **Apps** → **Installed apps** +2. Find **WSA Installer** in the list +3. Click the three dots (**) → **Uninstall** +4. Follow the uninstall wizard + +### Method 2: From WSA Installer + +1. Open WSA Installer +2. Click **Advanced** in the sidebar +3. Click **Uninstall WSA** button +4. Follow the uninstall wizard + +### Method 3: Command Line + +```cmd +WSAInstaller.exe --uninstall +``` + +### Method 4: From Start Menu + +1. Open the Start Menu +2. Find **WSA Installer** folder +3. Click **Uninstall** + +## Uninstall Process + +The uninstall wizard performs 7 steps: + +### Step 1: Detect WSA + +Locates the WSA installation using `Get-AppxPackage`. + +### Step 2: Stop WSA Processes + +Terminates all WSA-related processes: +- `WsaClient.exe` +- `WsaService.exe` +- `WsaSvc` +- `vmmem` +- `adb.exe` + +### Step 3: Backup User Data (Optional) + +You can choose to back up your WSA data before uninstalling. This preserves: +- Installed apps +- App data +- Settings + +### Step 4: Remove Appx Package + +Runs `Remove-AppxPackage` to remove WSA from Windows. If this fails, it retries with `-AllUsers`. + +### Step 5: Delete Installation Files + +Removes the WSA installation directory and all associated files. + +### Step 6: Remove Background Service + +Stops and deletes `WSABackgroundService` from Windows Services. + +### Step 7: Cleanup + +Final cleanup of: +- Desktop shortcuts +- Start Menu shortcuts +- Registry entries +- Temporary files + +## What Gets Removed + +| Component | Removed? | +|:----------|:---------| +| WSA installation | Yes | +| WSA app data | Optional (backup available) | +| Background service | Yes | +| Desktop shortcuts | Yes | +| Start Menu shortcuts | Yes | +| Registry entries | Yes | +| WSA Installer | Yes | +| Downloaded bundles | No (preserved for reinstall) | + +## Preserved Data + +The following data is NOT removed during uninstall: + +- Downloaded `bundle.wsa` files +- WSA backup (if created) +- Activity logs (`wsa_activity.log`) + +## Silent Uninstall + +For automated uninstall: + +```cmd +Uninstall.exe /S +``` + +## Canceling Uninstall + +The uninstall wizard includes a confirmation step with a countdown timer. You must: + +1. Check the confirmation checkbox +2. Wait 3 seconds +3. Click **Confirm Uninstall** + +You can cancel at any time before confirming. If you cancel after confirmation has started, the uninstall will stop at the current step. + +## Troubleshooting + +### Uninstall Fails + +1. Try running as administrator +2. Ensure no other applications are using WSA files +3. Manually stop the service: `sc stop WSABackgroundService` +4. Manually kill processes: `taskkill /F /IM WsaClient.exe` +5. Retry uninstall + +### Files Remain After Uninstall + +If some files remain after uninstall: + +1. Restart your computer +2. Navigate to the installation directory +3. Delete remaining files manually +4. Remove the directory + +### Service Won't Delete + +If `WSABackgroundService` won't delete: + +```cmd +sc stop WSABackgroundService +sc delete WSABackgroundService +``` + +Then retry the uninstall. diff --git a/docs/webdav.md b/docs/webdav.md new file mode 100644 index 0000000..4d828de --- /dev/null +++ b/docs/webdav.md @@ -0,0 +1,204 @@ +# File Sharing (WebDAV) Guide + +WSA Installer includes a WebDAV-based file sharing feature that mounts your WSA file system as a Windows network drive, allowing you to access Android files directly from File Explorer. + +## Overview + +File sharing uses a WebDAV server running inside WSA to serve files over HTTP. Windows mounts this as a network drive, making Android files accessible like any other folder. + +### Modes + +| Mode | Access | Requirements | +|:-----|:-------|:-------------| +| User Mode | `/storage/emulated/0` (user storage) | WSA installed | +| Root Mode | `/` (full filesystem) | WSA + Magisk root | + +## How to Enable + +### Method 1: From WSA Installer + +1. Open WSA Installer +2. Click **Advanced** in the sidebar +3. Select the file sharing mode (User or Root) +4. Choose a drive letter +5. Toggle the switch to enable + +### Method 2: Command Line + +```cmd +WSA Installer.exe --file-sharing +WSA Installer.exe --file-sharing root +``` + +## Setup Process + +The file sharing setup performs these steps: + +### Step 1: Check WSA + +Verifies WSA is installed on the system. + +### Step 2: Ensure WSA Running + +Starts WSA if not already running. Waits for the ADB port (58526) to become available. + +### Step 3: Connect ADB + +Establishes an ADB connection to WSA (15 attempts with server restart). + +### Step 4: Install WebDAV APK + +Installs `com.wsa.webdav` APK via ADB. This APK contains: +- WebDAV server +- Web file manager SPA +- Shell control script + +### Step 5: Detect Root (Root Mode Only) + +Checks if Magisk is installed and root access is available via `su -c whoami`. + +### Step 6: Start WebDAV Server + +**User Mode:** +```cmd +adb shell am start -n com.wsa.webdav/.MainActivity +``` + +**Root Mode:** +```cmd +adb shell su -c "sh /data/data/com.wsa.webdav/files/app.sh start" +``` + +### Step 7: Port Forwarding + +Forwards port 8088 from WSA to localhost: +```cmd +adb forward tcp:8088 tcp:8088 +``` + +### Step 8: Configure Windows WebClient + +Configures Windows to support WebDAV: +- Sets `BasicAuthLevel=2` (allows basic auth over HTTP) +- Sets `FileSizeLimitInBytes=4GB` +- Starts the WebClient service + +### Step 9: Mount Network Drive + +Mounts the WebDAV share as a Windows drive: +```cmd +net use X: http://127.0.0.1:8088/files/ /persistent:yes +``` + +### Step 10: Set Drive Icon and Label + +Configures the drive icon and label in Windows Registry: +- `DriveIcons\X\DefaultLabel` = "WSA Files" +- `DriveIcons\X\DefaultIcon` = custom icon + +## Using File Sharing + +### Access Files + +1. Open File Explorer +2. Look for the mounted drive (e.g., "WSA Files (X:)") +3. Browse and manage files like any other drive + +### Web File Manager + +You can also access files via web browser: + +1. Open `http://127.0.0.1:8088` in your browser +2. Use the web file manager interface +3. Upload, download, and manage files + +### Root File System (Root Mode) + +In root mode, the root filesystem is mounted at: +``` +X:\root\ +``` + +User storage is at: +``` +X:\files\ +``` + +## Configuration + +### Config File + +The WebDAV server configuration is at: +``` +/data/data/com.wsa.webdav/files/config.json +``` + +### Default Settings + +| Setting | Value | +|:--------|:------| +| Port | 8088 | +| Host | 127.0.0.1 | +| Root Access | true | +| Anonymous Access | true | +| Max Connections | 50 | + +### Changing the Port + +1. Edit `config.json` in WSA +2. Restart the WebDAV server +3. Update the port forward: + ```cmd + adb forward tcp:NEW_PORT tcp:NEW_PORT + ``` +4. Remount with the new port + +## Troubleshooting + +### Drive Won't Mount + +1. Ensure WSA is running +2. Check ADB connection: `adb devices` +3. Verify WebDAV server is running: `curl http://127.0.0.1:8088` +4. Check WebClient service: `services.msc` → WebDAV Redirector + +### "Network Error" in Browser + +1. Check if port 8088 is forwarded: `adb forward --list` +2. Re-establish forwarding: `adb forward tcp:8088 tcp:8088` +3. Check firewall settings + +### Slow Performance + +1. Use USB instead of WiFi ADB +2. Reduce the number of concurrent connections +3. Close other network-intensive applications + +### Root Access Denied + +1. Ensure Magisk is installed in WSA +2. Open Magisk app and grant root to WSA WebDAV +3. Check `su -c whoami` returns "root" + +### Files Not Updating + +1. The WebDAV server may need a restart +2. Disconnect and remount the drive: + ```cmd + net use X: /delete + net use X: http://127.0.0.1:8088/files/ /persistent:yes + ``` + +## Stopping File Sharing + +To stop file sharing: + +1. Open WSA Installer → Advanced +2. Toggle file sharing off + +Or manually: +```cmd +net use X: /delete +adb shell am broadcast -a com.wsa.webdav.STOP +adb forward --remove tcp:8088 +```