service-update-alerts/BACKLOG.md

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.