# 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.

## Setup And Commands

- 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.

## Runtime Constraints

- 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.

## Source And Test Details

- 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.