# Backlog: check-for-updates

## US-01 - Parse Uptime Status Page

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.

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.

## US-02 - Service Configuration Mapping

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.

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.

## US-03 - Version Detection Framework

As a maintainer, I want a reusable framework of version detection strategies so that different services can report their running version reliably.

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.

## US-04 - Service-Specific Version Strategies

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.

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.

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