Agent Guide

Project Shape

This is a small Python project: the runtime entrypoint is src/sideload.py; tests are in tests/test_sideload.py.
The package requires Python 3.11+ because configuration is parsed with the standard-library tomllib.
The sideload console command is declared in pyproject.toml; install the project editable before using it from a checkout.

Recommended setup: python -m venv .venv && .venv/bin/pip install -e ..
Run the full test suite with python -m pytest tests -q or python -m pytest tests/ -v.
Run the CLI help after editable installation with .venv/bin/sideload --help.
Use config.example.toml as the template and copy it to the Git-ignored config.toml; do not add a real configuration containing local devices or app choices.
No linter, formatter, type checker, code generator, or CI workflow is configured; tests and python -m compileall -q src tests are the available local checks.

Real installations require adb and either aapt2 or aapt in PATH; tests must continue to mock them rather than require a phone or Android SDK.
aapt2 dump packagename (with aapt dump badging fallback) is mandatory pre-install validation; never add an installation path that bypasses package-ID validation.
ADB commands must remain argument lists passed with shell=False; do not construct shell command strings or use shell=True.
Multiple connected ADB devices require explicit interactive selection or --device/-s; never silently choose the first device.
Wi-Fi ADB uses an explicit HOST:PORT from [adb]; do not add network scanning or implicit device discovery.
Downloads are HTTPS-only and cached under the configured cache directory; preserve SHA-256 checks and atomic temporary-file downloads.

Application entries use name, package, source, and url; GitHub/GitLab entries may need asset_pattern when a release has multiple APKs.
F-Droid resolution reads index-v2.json and versions are nested under packages[package].versions; keep numeric versionCode ordering and correct URL joining.
GitHub and GitLab release parsing must reject ambiguous APK assets instead of selecting arbitrarily; do not treat GitLab source archives as APKs.
Network, ADB, and Android SDK tool behavior is mocked in the unit tests; add response fixtures or mocks for new integrations instead of live API tests.