4.2 KiB
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
--configCLI 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.
--allprints 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
--timeoutand--user-agentflags. - Defaults are documented in
--helpoutput. - 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.