From 29f0684127a7012c105190043f9914a1765f3e82 Mon Sep 17 00:00:00 2001 From: Antoine Van Elstraete Date: Sat, 8 Aug 2026 18:57:08 +0200 Subject: [PATCH] docs: add French documentation --- AGENTS.md | 4 +++ README.fr.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 14 +++++++- 3 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 README.fr.md diff --git a/AGENTS.md b/AGENTS.md index c41c23e..5f54427 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,11 +13,14 @@ - 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. @@ -29,3 +32,4 @@ - 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. diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..dc9f6e4 --- /dev/null +++ b/README.fr.md @@ -0,0 +1,91 @@ +# adb-sideload-free-apps + +Installer des applications Android libres avec ADB depuis F-Droid, les releases GitHub, +GitLab ou Codeberg, ou des pages HTTPS génériques. + +[English](README.md) + +## Prérequis + +- Python 3.11 ou supérieur +- `adb` (Android Debug Bridge) dans le `PATH` +- `aapt2` ou `aapt` (Android SDK Build Tools) dans le `PATH` + +## Démarrage rapide + +```bash +python -m pip install -e . +cp config.example.toml config.toml +# Modifier config.toml pour ajouter les applications +python -m sideload +``` + +## Utilisation + +```text +sideload [APP] [--list] [--update-all] [--device SERIAL] [--dry-run] [--config PATH] +``` + +- `APP` : nom de l’application dans la configuration (omettre pour la sélection interactive) +- `--list` : lister les applications configurées +- `--device`, `-s` : numéro de série du périphérique ADB +- `--dry-run` : résoudre, télécharger et valider sans installer +- `--update-all` : inspecter toutes les applications configurées sur un périphérique choisi + une seule fois et mettre à jour uniquement les applications installées dont l’APK distant + possède un `versionCode` supérieur (incompatible avec `APP` et `--list`) +- `--config`, `-c` : chemin vers `config.toml` (par défaut : `./config.toml`) + +`--update-all` sélectionne le périphérique ADB une seule fois, puis vérifie chaque paquet +configuré avec `adb shell dumpsys package`. Les applications absentes du périphérique sont +signalées et ignorées sans téléchargement. Une application installée est mise à jour +uniquement lorsque l’APK distant validé possède un `versionCode` strictement supérieur ; les +versions égales ou inférieures sont ignorées. Une erreur sur une application n’interrompt pas +le traitement des suivantes. La commande affiche un bilan et retourne un code non nul si une +mise à jour a échoué. + +## Configuration + +Voir `config.example.toml`. Les sources prises en charge sont : + +| Source | Champs requis | +| --- | --- | +| `fdroid` | `url` (page F-Droid) | +| `github` | `url` (dépôt) | +| `gitlab` | `url` (projet) | +| `codeberg` | `url` (dépôt Codeberg) | +| `generic` | `url`, `asset_pattern` (page ou répertoire HTTPS) | + +Chaque application doit aussi définir `name` et `package`. Pour GitHub, GitLab et Codeberg, +définir `asset_pattern` lorsqu’une release contient plusieurs APK compatibles. Les APK de +debug, de test et non signés sont rejetés par défaut. + +La source `generic` suit les liens HTML HTTPS depuis `url`. Utiliser +`intermediate_patterns` dans l’ordre pour parcourir les répertoires ; lorsque plusieurs liens +correspondent, un motif avec des groupes de capture numériques sélectionne le plus grand tuple +numérique. `asset_pattern` est obligatoire et doit correspondre à un seul APK final. Les champs +optionnels `headers` et `sha256` sont pris en charge ; les valeurs des en-têtes ne sont jamais +écrites dans les logs. + +`aapt2` valide l’identifiant du paquet APK avant l’installation, avec `aapt` comme solution de +secours pour les anciennes versions des Android SDK Build Tools. Au moins un des deux outils +doit être disponible dans le `PATH`. Le script refuse d’installer un APK si aucun outil ne peut +le valider. + +Avec `--update-all`, `aapt2 dump badging` (avec fallback `aapt dump badging`) lit également le +`versionCode` de l’APK distant avant de décider si une installation est nécessaire. + +Pour utiliser ADB en Wi-Fi, configurer une adresse explicite après avoir activé le débogage sans +fil : + +```toml +[adb] +mode = "wifi" +address = "192.168.1.42:5555" +``` + +## Tests + +```bash +pip install pytest +python -m pytest tests/ -v +``` diff --git a/README.md b/README.md index ad92bc7..8783fa4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Install free Android apps via ADB from F-Droid, GitHub Releases, GitLab Releases, Codeberg Releases, or generic HTTPS pages. +[Français](README.fr.md) + ## Requirements - Python 3.11+ @@ -31,6 +33,13 @@ sideload [APP] [--list] [--update-all] [--device SERIAL] [--dry-run] [--config P installed apps whose remote APK has a greater `versionCode` (incompatible with `APP` and `--list`) - `--config`, `-c` — path to config.toml (default: ./config.toml) +`--update-all` selects the ADB device once, then checks every configured package with +`adb shell dumpsys package`. Apps that are not installed are reported and skipped without +downloading anything. Installed apps are updated only when the validated remote APK has a +strictly greater `versionCode`; equal or lower versions are skipped. Errors for one app do +not stop the other apps, and the command prints a summary and returns a non-zero status if +an update failed. + ## Configuration See `config.example.toml`. Supported sources: @@ -39,7 +48,7 @@ See `config.example.toml`. Supported sources: | -------- | ---------------------------- | | `fdroid` | `url` (page F-Droid) | | `github` | `url` (repository) | -| `gitlab` | `url` (projet) | +| `gitlab` | `url` (project) | | `codeberg` | `url` (repository Codeberg) | | `generic` | `url`, `asset_pattern` (HTTPS page or directory) | @@ -58,6 +67,9 @@ pattern with numeric capture groups selects the greatest numeric tuple. must be available in `PATH`. The script refuses to install an APK when neither tool can validate it. +For `--update-all`, `aapt2 dump badging` (with `aapt dump badging` fallback) also reads the +remote APK `versionCode` before deciding whether an installation is needed. + For Wi-Fi ADB, configure an explicit address after enabling wireless debugging: ```toml