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.
README.md is the canonical English user documentation; README.fr.md is its French translation. Keep the language links and user-facing behavior synchronized when changing the CLI.

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.
--update-all must read the installed versionCode with adb shell dumpsys package, read the remote APK versionCode with aapt2 dump badging (falling back to aapt dump badging), and install only when the remote code is strictly greater.
--update-all must report configured apps that are not installed without downloading them, continue after per-app errors, and print a final summary. Device preparation and selection must happen once per batch.
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.
Tests for --update-all should cover absent packages, equal/older/newer version codes, aapt2 fallback, dry-run, partial failures, summary output, and the single-device preparation path.