# Backlog: service-update-alerts ## US-01 - Curated Webservice Dataset 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: - 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-01A - Sample Environment File As a maintainer, I want a `.env.sample` file listing required authentication variables so that I can configure the script quickly. Acceptance criteria: - `.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-02 - Service Research Dataset 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: - 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-03 - Dataset Loader and Validation As a maintainer, I want to load and validate the curated dataset so that the script can operate consistently on structured inputs. Acceptance criteria: - 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 As a maintainer, I want to query upstream release APIs (GitHub and Codeberg) so that I can compare current and latest versions. Acceptance criteria: - The script can fetch the latest release for GitHub repositories. - The script can fetch the latest release for Codeberg repositories. - If no releases are available, the script can fall back to the latest tag. ## US-06 - Version Normalization and Comparison As a maintainer, I want version strings normalized and compared consistently so that update checks are accurate. Acceptance criteria: - Versions are normalized to handle leading "v" and common tag formats. - Semantic versions are compared using a proper parser. - Unparseable versions are flagged and still reported. ## US-07 - Update Report Output As a maintainer, I want the script to print only services with updates by default, and optionally all services, so that I can focus on actionable results. Acceptance criteria: - Default output includes only services where latest > running. - `--all` prints all services including up-to-date and unknown versions. - Output includes service name, running version, latest version, and upstream URL. ## US-08 - CLI and Runtime Options As a maintainer, I want a simple CLI with timeouts and user-agent settings so that the script works reliably in different environments. Acceptance criteria: - The script supports `--timeout` and `--user-agent` flags. - Defaults are documented in `--help` output. - Invalid arguments produce a helpful error message. ## US-09 - Resilience and Errors As a maintainer, I want network failures and API errors handled gracefully so that one bad service does not break the whole run. Acceptance criteria: - Network timeouts and HTTP errors are logged per service. - The script continues processing remaining services after a failure. - The final exit code is non-zero only for total failure (e.g., cannot fetch service list). ## US-10 - Output Formatting and Exit Codes As a maintainer, I want consistent output formatting and exit codes so that this script can be used in cron jobs or CI. 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. ## US-13 - FreshRSS Authenticated Version Check As a maintainer, I want FreshRSS version detection to authenticate with a username and password so that the script can read the About page and extract the running version. Acceptance criteria: - The script can log in to FreshRSS using credentials from environment variables. - FreshRSS version is extracted from the About page after authentication. - `.env.sample` documents the FreshRSS credentials required. ## US-14 - Matrix Notifications As a maintainer, I want the script to post update alerts to a Matrix room so that I can track service changes and failures without email. Acceptance criteria: - The script posts a message to a Matrix room when updates are detected or errors occur. - Matrix credentials (homeserver, room id, access token) are read from `.env`. - The message includes actionable service names and version details. ## US-15 - Systemd User Service As a maintainer, I want a systemd user service and timer so the script runs daily without manual intervention. Acceptance criteria: - Provide a user-level systemd service file that runs the update checker. - Provide a user-level timer that runs once per day. - README documents how to install and enable the service and timer. ## US-16 - Uptime Kuma Push As a maintainer, I want the script to call an Uptime Kuma push URL on each run so that failures are visible in the monitoring dashboard. Acceptance criteria: - The script sends a request to the push URL when it runs. - The push URL is configured via `.env`. - Failures to reach the push URL are logged without crashing the run.