jeena/service-update-alerts
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: Add update checker tooling

Browse source 
Add the initial dataset, version checker, tests, and project setup files so the update checker can be run and validated.
This commit is contained in:
Jeena 2026-03-12 12:49:28 +00:00
parent 1eddaca1ad
commit 95cd8e0906
10 changed files with 692 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

67
BACKLOG.md
View file

@ -1,40 +1,49 @@
# Backlog: check-for-updates
## US-01 - Parse Uptime Status Page
## US-01 - Curated Webservice Dataset
As a maintainer, I want the script to fetch and parse the services listed on `https://uptime.jeena.net/status/everything` so that I have a normalized list of hosted services to check.
As a maintainer, I want a curated YAML dataset of webservices to check so that the script does not rely on scraping a status page.
Acceptance criteria:
- Given the status page is reachable, the script extracts service name and URL for each monitored service.
- Parsed services are normalized for consistent URL handling (scheme and trailing slash).
- Failures to fetch or parse are reported with a clear error message and non-zero exit.
- A YAML file contains the full list of webservices (name + base URL).
- Each entry supports version endpoint and upstream metadata fields, even if left empty initially.
- The script can load the dataset without performing any network discovery.
## US-02 - Service Configuration Mapping
## US-01A - Sample Environment File
As a maintainer, I want to provide a config file that maps services to upstream sources and version detection strategies so that the script can work reliably across heterogeneous services.
As a maintainer, I want a `.env.sample` file listing required authentication variables so that I can configure the script quickly.
Acceptance criteria:
- The script accepts a `--config` CLI argument and reads a YAML/JSON/TOML file.
- Each config entry supports: service name, URL, upstream type, repo identifier, and version strategy.
- Invalid config formats are rejected with a clear error message.
- `.env.sample` exists and lists required auth environment variables.
- Each variable includes a short note about its expected format.
- Optional variables are clearly marked.
## US-03 - Version Detection Framework
## US-02 - Service Research Dataset
As a maintainer, I want a reusable framework of version detection strategies so that different services can report their running version reliably.
As a maintainer, I want to research and populate version endpoints and upstream release sources for each webservice so that checks are reliable without guesswork.
Acceptance criteria:
- The script supports a registry of detection strategies.
- At least one strategy uses common version endpoints (e.g., `/version`, `/health`, `/api/version`).
- The script records "unknown" when no version can be detected.
- Each webservice entry includes `current_version_url` and `upstream_latest_version_url`.
- Each entry includes extraction rules for both current and latest versions.
- Services without a viable version endpoint are clearly marked with notes and `current_version_url` left empty.
## US-04 - Service-Specific Version Strategies
## US-03 - Dataset Loader and Validation
As a maintainer, I want service-specific version detection for common tools (e.g., Gitea/Forgejo/Nextcloud/Miniflux) so that versions are detected accurately where possible.
As a maintainer, I want to load and validate the curated dataset so that the script can operate consistently on structured inputs.
Acceptance criteria:
- At least one named strategy queries a known service API endpoint.
- Strategies can be selected per service via config.
- If the service endpoint fails, the result is marked unknown without crashing the run.
- The script accepts a `--config` CLI argument and reads a YAML file.
- The dataset is validated for required fields and data types.
- Invalid datasets are rejected with a clear error message.
## US-04 - Version Fetching and Parsing
As a maintainer, I want to fetch versions using dataset-defined endpoints and extraction rules so that version detection is consistent across services.
Acceptance criteria:
- The script fetches `current_version_url` for each service.
- The script applies the dataset extraction rule to obtain the running version.
- Failures are logged per service without aborting the run.
## US-05 - Upstream Release Lookup
@ -89,3 +98,21 @@ Acceptance criteria:
- The script exits with code 0 when it completes a run.
- The script exits with code 1 on unrecoverable setup failures.
- Output is stable across runs for the same inputs.
## US-11 - Automated Tests
As a maintainer, I want tests for extraction and version comparison so that changes can be verified quickly.
Acceptance criteria:
- Tests cover JSONPath, regex, and header extraction.
- Tests cover version comparison including prerelease handling.
- Tests run with pytest.
## US-12 - Python Project Setup
As a maintainer, I want a virtual environment workflow with `pyproject.toml` so that dependencies are managed consistently.
Acceptance criteria:
- `pyproject.toml` defines runtime and dev dependencies.
- README documents venv setup and installation commands.
- `.venv` is ignored by git.