# Backlog: check-for-updates

## 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.