Fix CI usage error tests, add the coverage badge and README header

- Typer styles and wraps usage errors in a panel when GITHUB_ACTIONS is set,
  so four CLI tests now compare the message's plain text (usage_error)
- CI writes the coverage total as a shields.io endpoint file, and
  badges.yml commits it to the badges branch after a passing run on main
- The README opens with the Libre DevOps logo and centred badges, as the
  organisation profile does, with a rule between sections and a footer

Author: craigthackerx

.github/workflows/badges.yml

@@ -0,0 +1,83 @@
+name: Badges
+
+# Publishes the README's coverage badge. After 'Lint and Test' passes on a push to main,
+# the coverage total it wrote (a shields.io endpoint file) is committed to the 'badges'
+# branch, which holds nothing else; the README reads it through img.shields.io/endpoint.
+# No third-party service is involved. This is a workflow of its own because the release
+# calls ci.yml with read-only permissions, and a job there cannot ask for more.
+on:
+  workflow_run:
+    workflows: ["Lint and Test"]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: badges
+  cancel-in-progress: false
+
+jobs:
+  coverage:
+    name: Coverage badge
+    # Only a passing run from a push to this repository's main: never a pull request.
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      # Pushing to the badges branch, and reading the triggering run's artifact.
+      contents: write
+      actions: read
+
+    steps:
+      - name: Fetch the badge
+        uses: actions/download-artifact@v8
+        with:
+          name: coverage-badge
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      # The file is published as it is, so check it is exactly the shape expected.
+      - name: Check the badge
+        run: |
+          python3 - <<'PY'
+          import json
+          import re
+
+          with open("coverage-badge.json", encoding="utf-8") as handle:
+              badge = json.load(handle)
+          assert set(badge) == {"schemaVersion", "label", "message", "color"}, badge
+          assert badge["schemaVersion"] == 1 and badge["label"] == "coverage", badge
+          assert re.fullmatch(r"\d{1,3}\.\d%", badge["message"]), badge
+          assert badge["color"] in {"brightgreen", "green", "yellow", "red"}, badge
+          PY
+
+      - name: Publish to the badges branch
+        env:
+          GH_TOKEN: ${{ github.token }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          set -euo pipefail
+          remote="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          if git ls-remote --exit-code --heads "$remote" badges > /dev/null; then
+            git clone --quiet --depth 1 --branch badges "$remote" "$RUNNER_TEMP/badges"
+          else
+            git init --quiet --initial-branch badges "$RUNNER_TEMP/badges"
+            git -C "$RUNNER_TEMP/badges" remote add origin "$remote"
+          fi
+          cp coverage-badge.json "$RUNNER_TEMP/badges/coverage.json"
+          cd "$RUNNER_TEMP/badges"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add coverage.json
+          if git diff --cached --quiet; then
+            echo "coverage unchanged"
+            exit 0
+          fi
+          git commit --quiet --message "Coverage $(python3 -c 'import json; print(json.load(open("coverage.json"))["message"])') at ${SHA:0:7}"
+          git push --quiet origin badges

.github/workflows/ci.yml

@@ -176,6 +176,30 @@ jobs:
           if-no-files-found: ignore
           retention-days: 14
 
+      # The total as a shields.io endpoint; badges.yml publishes it for the README badge
+      # after a push to main.
+      - name: Write the coverage badge
+        shell: bash
+        run: |
+          total="$(uv run coverage report --format=total --precision=1 --fail-under=0)"
+          python3 - "$total" > coverage-badge.json <<'PY'
+          import json
+          import sys
+
+          total = float(sys.argv[1])
+          colour = next(c for floor, c in ((90, "brightgreen"), (80, "green"), (70, "yellow"), (0, "red")) if total >= floor)
+          print(json.dumps({"schemaVersion": 1, "label": "coverage", "message": f"{total:.1f}%", "color": colour}))
+          PY
+          cat coverage-badge.json
+
+      - name: Keep the badge
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-badge
+          path: coverage-badge.json
+          if-no-files-found: error
+          retention-days: 14
+
   build:
     name: Build
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -26,6 +26,8 @@ All notable changes to libre-devops-helpers are recorded here. The project follo
   Azure CLI's lock file current.
 - `just image`, `image-slim`, `image-run` and `image-scan`, and `just coverage`.
 - Line and branch coverage in CI, failing below a floor set in `pyproject.toml`.
+  The README's coverage badge comes from CI too: `badges.yml` publishes the total to a
+  `badges` branch after each passing run on main, with no third-party service.
 - Signing in again when a sign-in lapses. When the Azure CLI's refresh token has run out
   (a sign-in frequency policy, 90 days unused, a password change, a revoked session, new
   MFA), the error now names the cause (`ReauthRequired`, with the Entra ID code
@@ -88,10 +90,14 @@ All notable changes to libre-devops-helpers are recorded here. The project follo
   concern; a test keeps the two trees in step. Many more CLI paths are tested.
 - A release now publishes the container images before the GitHub release, so a release
   never exists without them.
+- The README opens with the Libre DevOps logo and centred badges, as the organisation's
+  profile does, with a rule between sections.
 
 ### Fixed
 
 - `just use` and `just token` ran commands that had moved under `az` and `entra`.
+- Four CLI tests failed in GitHub Actions, where Typer styles and wraps usage errors; they
+  now compare the message's plain text.
 
 ### Security
 

README.md

@@ -1,11 +1,30 @@
+<div align="center">
+
+<a href="https://libredevops.org">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://libredevops.org/assets/libre-devops-white.png">
+    <img alt="Libre DevOps" src="https://libredevops.org/assets/libre-devops-black.png" width="320">
+  </picture>
+</a>
+
 # Libre DevOps Helpers
 
+`ldo`: importable Python helpers and a fast CLI for day-to-day DevOps and security work.
+
 [![Lint and Test](https://github.com/libre-devops/python-helpers/actions/workflows/ci.yml/badge.svg)](https://github.com/libre-devops/python-helpers/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/libre-devops/python-helpers/badges/coverage.json)](https://github.com/libre-devops/python-helpers/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/libre-devops/python-helpers/actions/workflows/codeql.yml/badge.svg)](https://github.com/libre-devops/python-helpers/actions/workflows/codeql.yml)
 [![Container](https://github.com/libre-devops/python-helpers/actions/workflows/container.yml/badge.svg)](https://github.com/libre-devops/python-helpers/actions/workflows/container.yml)
+
+[![Release](https://img.shields.io/github/v/release/libre-devops/python-helpers?label=release&color=1793D1)](https://github.com/libre-devops/python-helpers/releases)
+[![Container images](https://img.shields.io/badge/ghcr.io-python--helpers-2496ED?logo=docker&logoColor=white)](https://github.com/libre-devops/python-helpers/pkgs/container/python-helpers)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&logoColor=white)](pyproject.toml)
 [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
 
-`ldo`: importable Python helpers and a fast CLI for day-to-day DevOps and security work.
+</div>
+
+---
+
 The Python sibling of the [LibreDevOpsHelpers](https://github.com/libre-devops/powershell-helpers)
 PowerShell module.
 
@@ -38,6 +57,8 @@ Azure CLI's active account.
 The whole project can be renamed for your organisation with one command; see
 [Rebranding](#rebranding).
 
+---
+
 ## Requirements
 
 - Python 3.11 or later, and [uv](https://docs.astral.sh/uv/)
@@ -47,6 +68,8 @@ The whole project can be renamed for your organisation with one command; see
 - [just](https://just.systems/) is optional: `uv sync` installs it into the project
   environment (the `rust-just` package), so `uv run just ...` always works
 
+---
+
 ## Install
 
 ```bash
@@ -70,6 +93,8 @@ Run `ldo` on its own, or `ldo welcome`, for a greeting and the next step. The ba
 appears on a terminal, so scripts and CI never see it; set `LDO_NO_BANNER=1` to turn it off
 there too, or `NO_COLOR=1` to keep it without colour.
 
+---
+
 ## Container images
 
 Each release is published to GitHub Container Registry in two variants, for `linux/amd64`
@@ -153,6 +178,8 @@ identity, managed identity, and browser or device code sign-in without `az`. The
 is only there for the default sign-in, which reuses the session you already have, so it
 stays an outside program: on your `PATH`, or inside the default image.
 
+---
+
 ## Configuration
 
 `config init` writes `~/.config/ldo/config.toml` (override with `--config` or `LDO_CONFIG`;
@@ -360,6 +387,8 @@ client_id = "<the app id printed above>"
 
 Graph insists on a ReadWrite scope even to list PIM requests; `ldo` still only ever reads.
 
+---
+
 ## Commands
 
 ```bash
@@ -651,6 +680,8 @@ type-checks the whole of it and creates nothing: the authority the offline check
 
 Code 3 lets a scheduled job alert on findings while still failing loudly on errors.
 
+---
+
 ## ServiceNow
 
 The `snow` commands sign in to a ServiceNow instance as you, and read from it:
@@ -748,6 +779,8 @@ If it is not offered there, sign in to the instance as admin and install it from
 System Applications > All Available Applications, with its demo data if you want records
 to work with. Then `ldo snow instance` shows it installed.
 
+---
+
 ## Permissions
 
 Commands run with the permissions of the profile's credential. The Azure CLI's delegated
@@ -790,6 +823,8 @@ The signature is **not** verified: this answers "is this the token I meant to ge
 this token genuine?". The token value is never printed unless you pass `--raw`, and never
 logged.
 
+---
+
 ## Rebranding
 
 To run this inside a company under the company's own name, rename it with one command.
@@ -818,7 +853,10 @@ the running tool shows come from one module (`core/brand.py`). After rewriting,
 refreshes the lock file and runs every check. `LICENSE` is never changed: the MIT licence
 requires its copyright and permission notice to stay with the code. A test rebrands a copy of
 the repository and runs the copy's whole test suite, so the rename keeps working as the code
-grows.
+grows. The README's logo, badges and footer point at Libre DevOps and this repository's
+GitHub pages, so replace them with your own by hand.
+
+---
 
 ## Using it as a library
 
@@ -865,6 +903,8 @@ with EntraClient.for_profile(profile, tokens) as entra, XdrClient.for_profile(pr
 Library code raises `LdoError` subclasses and never exits; only the CLI turns errors into
 messages and exit codes.
 
+---
+
 ## CI/CD
 
 Every pull request and push to `main` runs `.github/workflows/ci.yml`:
@@ -875,7 +915,7 @@ Every pull request and push to `main` runs `.github/workflows/ci.yml`:
 | Lint | `ruff check` and `ruff format --check`, after `uv sync --locked` |
 | Dependency audit | `pip-audit` over the locked, hashed dependency tree |
 | Test | pytest on Python 3.11 to 3.14 on Linux, and 3.13 on Windows and macOS, including the rebrand test |
-| Coverage | line and branch coverage, failing below the floor in `pyproject.toml` (`fail_under`), with the report in the job summary |
+| Coverage | line and branch coverage, failing below the floor in `pyproject.toml` (`fail_under`), with the report in the job summary and the total written for the badge |
 | Build | builds the sdist and wheel once, installs the wheel in a clean environment, and keeps both as the run's artifact |
 
 `.github/workflows/container.yml` builds both images on every pull request and push, runs
@@ -886,6 +926,10 @@ fixed critical one and reports the rest, since the Azure CLI inside it pins its
 dependencies. Findings
 go to the Security tab.
 
+After a passing run on `main`, `.github/workflows/badges.yml` commits the coverage total
+to the `badges` branch as a shields.io endpoint file, which is where the README's coverage
+badge reads it; nothing else lives on that branch.
+
 CodeQL scans the Python code and the workflows on every change and weekly; Dependency
 Review comments on pull requests that change dependencies. Third-party actions are pinned
 to a commit.
@@ -920,6 +964,8 @@ both container images for every platform, with attestations, and only then publi
 files the gate built (not a rebuild) as a GitHub release with `SHA256SUMS`, after checking
 the tag matches the version. A release therefore never exists without its images.
 
+---
+
 ## Development
 
 ```bash
@@ -943,6 +989,17 @@ so an hour-long watch runs in microseconds. Runtime dependencies are kept to `re
 See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request, and
 [SECURITY.md](SECURITY.md) to report a vulnerability.
 
+---
+
 ## Licence
 
 [MIT](LICENSE)
+
+---
+
+<div align="center">
+<sub>
+Part of <a href="https://libredevops.org">Libre DevOps</a>. Everything we publish is open and
+provided as-is; review and test it against your own requirements before production use.
+</sub>
+</div>

tests/cli/commands/test_azure.py

@@ -2,7 +2,7 @@
 
 from fakes.http import routes
 from fakes.ids import OTHER_SUBSCRIPTION, SUBSCRIPTION, TENANT
-from fakes.tenant import invoke, run
+from fakes.tenant import invoke, run, usage_error
 
 SECURITY = f"/subscriptions/{SUBSCRIPTION}/providers/Microsoft.Security"
 SUBSCRIPTIONS = (
@@ -96,7 +96,7 @@ def test_recommendations_filter_by_severity_across_subscriptions(config_file):
 def test_recommendations_reject_an_unknown_severity(config_file):
     result = run(config_file, routes({}), ["azure", "recommendations", "--severity", "urgent"])
     assert result.exit_code == 2
-    assert "--severity must be high, medium or low" in result.output
+    assert "--severity must be high, medium or low" in usage_error(result)
 
 
 def test_defender_plans_show_which_are_on(config_file):

tests/cli/commands/test_entra.py

@@ -1,7 +1,7 @@
 import json
 
 from fakes.http import routes
-from fakes.tenant import invoke, run, runner, runtime
+from fakes.tenant import invoke, run, runner, runtime, usage_error
 from libre_devops_helpers.cli import app
 
 GROUP_ID = "55555555-5555-5555-5555-555555555555"
@@ -112,7 +112,7 @@ def test_group_members_of_one_kind(config_file):
 def test_group_members_rejects_an_unknown_kind(config_file):
     result = run(config_file, routes({}), ["entra", "group-members", "Ring 1", "--kind", "robot"])
     assert result.exit_code == 2
-    assert "--kind must be one of" in result.output
+    assert "--kind must be one of" in usage_error(result)
 
 
 def test_user_groups_for_a_upn(config_file):

tests/cli/commands/test_keyvault.py

@@ -1,7 +1,7 @@
 import json
 
 from fakes.http import routes
-from fakes.tenant import invoke, run
+from fakes.tenant import invoke, run, usage_error
 
 
 def test_keyvault_expiry_finds_vaults_through_resource_graph(config_file, tenant):
@@ -41,4 +41,4 @@ def test_expiry_needs_a_vault_and_a_known_kind(config_file):
     assert "no vaults given" in str(result.exception)
     result = run(config_file, routes({}), ["keyvault", "expiry", "kv-app", "--kind", "passwords"])
     assert result.exit_code == 2
-    assert "--kind must be one of" in result.output
+    assert "--kind must be one of" in usage_error(result)

tests/cli/commands/test_xdr.py

@@ -3,7 +3,7 @@
 from urllib.parse import unquote
 
 from fakes.http import json_body, routes
-from fakes.tenant import invoke, run, runner, runtime
+from fakes.tenant import invoke, run, runner, runtime, usage_error
 from libre_devops_helpers.cli import app
 
 MACHINE_ID = "a" * 40
@@ -179,4 +179,4 @@ def test_a_timespan_needs_graph(config_file):
     args = ["xdr", "hunt", "DeviceInfo", "--endpoint", "--timespan", "7d"]
     result = run(config_file, routes({}), args)
     assert result.exit_code == 2
-    assert "--timespan is not available with --endpoint" in result.output
+    assert "--timespan is not available with --endpoint" in usage_error(result)