36 lines
3.2 KiB
Markdown
36 lines
3.2 KiB
Markdown
# 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.
|
|
- `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.
|
|
|
|
## 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.
|
|
- `--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.
|
|
|
|
## 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.
|
|
- 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.
|