32 lines
2.4 KiB
Markdown
32 lines
2.4 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.
|
|
|
|
## Runtime Constraints
|
|
|
|
- Real installations require both `adb` and `apkanalyzer` in `PATH`; tests must continue to mock them rather than require a phone or Android SDK.
|
|
- `apkanalyzer manifest application-id` is a 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 `apkanalyzer` behavior is mocked in the unit tests; add response fixtures or mocks for new integrations instead of live API tests.
|