Merge pull request #15 from schubergphilis/feat/list-slo-downtime

Feat/list slo downtime

Author: Yhoorneman

.gitignore

@@ -220,3 +220,7 @@ cython_debug/
 
 ## Complexipy cache
 .complexipy_cache/
+
+# oh-my-claudecode operational state (keep project skills committable)
+.omc/
+!.omc/skills/

.security-overrides

@@ -23,6 +23,11 @@
 # GHSA-xxxx-yyyy-zzzz
 # PYSEC-2025-0001
 
-# pip 26.1.1 -> fixed in 26.1.2, but selection is blocked by [tool.uv] exclude-newer.
-# Expires so the audit re-checks once 26.1.2 is selectable via `uv lock --upgrade-package pip`.
-PYSEC-2026-196::2026-06-19
+# Both fixes exist on PyPI but are held back by [tool.uv] exclude-newer = "1 week"
+# (a release isn't selectable until it ages past the window). Time-boxed so the audit
+# re-checks once they're selectable via `uv lock --upgrade-package <pkg>`.
+#
+# pip 26.1.1 -> fixed in 26.1.2 (the installer; not shipped in the wheel).
+PYSEC-2026-196::2026-08-17
+# msgpack 1.1.2 (transitive via niquests) -> fixed in 1.2.1.
+GHSA-6v7p-g79w-8964::2026-08-17

README.md

@@ -45,9 +45,11 @@ Check the installed version with `datadog-slo-overrides --version`.
 
 | Command | What it does |
 |---------|--------------|
-| `run` | Preview (default) or `--apply` corrections to every SLO matching the tags. |
+| `set` | Preview (default) or `--apply` corrections (overrides) to every SLO matching the tags. |
+| `list` | List SLOs matching the tags and their monitor downtime in a window, excluding downtime already covered by an override. |
 | `init-config` | Write a starter config of non-secret defaults. |
 | `init-envrc` | Write a starter `.envrc` for optional, direnv-managed credential loading. |
+| `commands list` | Print a tree of every command this CLI provides. |
 
 ### Credentials
 
@@ -79,7 +81,7 @@ actionable hint instead of failing silently. The config dir honours `XDG_CONFIG_
 
 ### Idempotency strategies
 
-`run` is idempotent: re-running the same command never creates duplicate corrections.
+`set` is idempotent: re-running the same command never creates duplicate corrections.
 `--strategy` controls when an existing correction counts as already covering your window:
 
 | `--strategy` | Skips (creates nothing) when… |
@@ -93,14 +95,14 @@ actionable hint instead of failing silently. The config dir honours `XDG_CONFIG_
 Preview which SLOs would be corrected (dry run — nothing is written):
 
 ```sh
-datadog-slo-overrides run --tag app:gitlab --tag customer:sbp \
+datadog-slo-overrides set --tag app:gitlab --tag customer:sbp \
     --start 2026-06-10T22:00 --end 2026-06-11T00:00
 ```
 
 Apply a 2-hour scheduled-maintenance correction:
 
 ```sh
-datadog-slo-overrides run --tag app:gitlab --tag customer:sbp \
+datadog-slo-overrides set --tag app:gitlab --tag customer:sbp \
     --start 2026-06-10T22:00 --end 2026-06-11T00:00 \
     --category "Scheduled Maintenance" --description "DB maintenance" \
     --apply
@@ -125,7 +127,45 @@ the built-in defaults. Credentials are **never** read from this file.
 datadog-slo-overrides init-config
 ```
 
-Run `datadog-slo-overrides run --help` for the full list of options.
+Run `datadog-slo-overrides set --help` for the full list of options.
+
+### Listing downtime
+
+`list` shows each matching SLO's **monitor downtime** (from Datadog's Downtimes API) within a
+window, and **excludes any downtime already covered by an SLO correction (override)** — so what
+remains is the downtime that is *not* yet accounted for. The window defaults to the start of the
+current month through now; set `--start`/`--end` to change it. Tag selection is optional (omit both
+`--tag` and `--tags-query` to list every SLO).
+
+```sh
+# Uncovered downtime this month, for SLOs tagged app:gitlab:
+datadog-slo-overrides list --tag app:gitlab
+
+# A specific window:
+datadog-slo-overrides list --tag app:gitlab --start 2026-07-01 --end 2026-07-15
+```
+
+```text
+Tags query : app:gitlab
+Window     : 2026-07-01 00:00 → 2026-07-17 14:30 UTC
+Matched    : 2 SLO(s)
+
+SBP - SLO monitor for the sbp gitlab Website  (fbb8a2c3…)
+  monitors: 12345
+  • 2026-07-09 10:00 → 2026-07-09 11:00  (monitor 12345)  "deploy mute"
+```
+
+Only `type: monitor` SLOs link to monitors (via `monitor_ids`), so metric and time-slice SLOs show
+no monitor downtime. Downtimes targeted by monitor **tags/scope** (rather than a specific monitor
+id) can't be mapped to an SLO from the list alone, and are reported as a note at the end.
+
+### Command tree
+
+```sh
+datadog-slo-overrides commands list
+```
+
+Prints a tree of every command the CLI provides.
 <!-- usage-end -->
 
 ## Developing further

pyproject.toml

@@ -213,6 +213,12 @@ extra-paths = ["_CI/lib/vendor"]
 [tool.pylint.MASTER]
 init-hook = "import sys; sys.path.append('src/'); sys.path.append('_CI/lib/vendor/')"
 
+[tool.pylint.FORMAT]
+# The CLI is intentionally a single flat module (module name == package name);
+# it holds the full command surface plus thorough Google docstrings on every
+# helper, so allow more than the 1000-line default.
+max-module-lines = 2000
+
 [tool.pylint."MESSAGES CONTROL"]
 max-line-length = 120
 disable = [