libre-devops-helpers 0.4.1__tar.gz

libre_devops_helpers-0.4.1/.dockerignore

@@ -0,0 +1,12 @@
+# The build context for the Containerfile: podman and docker both read this file. Only
+# what the Containerfile copies is let in, so secrets and local environments stay out.
+*
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENSE
+!src/
+!container/azure-cli/pyproject.toml
+!container/azure-cli/uv.lock
+**/__pycache__
+**/*.pyc

libre_devops_helpers-0.4.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report something in ldo that is broken or not working as expected
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+<!-- Never paste an access token, tenant id, subscription id or real device name here.
+     Replace them with placeholders such as <tenant-id> or web01.example.com. -->
+
+## Description
+
+A clear description of what is broken or not working as expected.
+
+## Steps to Reproduce
+
+1. Run `ldo ...`
+2. Observe the issue
+
+## Expected Behaviour
+
+What should have happened?
+
+## Actual Behaviour
+
+What actually happened? Include the error and hint lines, and the exit code.
+
+## Environment
+
+- ldo version (`ldo --version`):
+- Azure CLI version (`az version`):
+- Python version:
+- OS:
+
+## Debug Output
+
+If useful, run the command again with `-vv` and paste the relevant lines, with any ids redacted.
+
+## Additional Context
+
+Anything else useful.

libre_devops_helpers-0.4.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/libre-devops/python-helpers/security/advisories/new
+    about: Please report vulnerabilities privately, not as a public issue.

libre_devops_helpers-0.4.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest an enhancement or new command for ldo
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+Describe the feature or improvement.
+
+## Problem Statement
+
+What problem does this solve, or what need does it address?
+
+## Proposed Solution
+
+What would you like to see implemented? If it calls a new Microsoft API, say which one and
+which permissions it needs.
+
+## Alternatives Considered
+
+Any other approaches you have thought of?
+
+## Additional Context
+
+Links, example output, or other relevant information.

libre_devops_helpers-0.4.1/.github/dependabot.yml

@@ -0,0 +1,68 @@
+version: 2
+updates:
+  # uv - pyproject.toml and uv.lock at the repository root. Minor and patch are
+  # grouped into one PR per week; majors get individual PRs so they can be
+  # reviewed separately.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/London
+    groups:
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: [minor, patch]
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+
+  # GitHub Actions - group all updates together. Dependabot keeps the SHA pin
+  # and its version comment in step for setup-uv.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/London
+    groups:
+      actions:
+        patterns: ["*"]
+    open-pull-requests-limit: 3
+    labels:
+      - dependencies
+      - github-actions
+
+  # Container base images (Containerfile). Dependabot moves the pinned digests when the
+  # python and uv images are rebuilt upstream, and proposes new Python versions; the
+  # weekly container workflow patches Debian packages in between.
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/London
+    groups:
+      base-images:
+        patterns: ["*"]
+    open-pull-requests-limit: 3
+    labels:
+      - dependencies
+
+  # The Azure CLI in the "az" image, locked in its own project.
+  - package-ecosystem: uv
+    directory: /container/azure-cli
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/London
+    groups:
+      azure-cli:
+        patterns: ["*"]
+    open-pull-requests-limit: 3
+    labels:
+      - dependencies

libre_devops_helpers-0.4.1/.github/pull_request_template.md

@@ -0,0 +1,34 @@
+## Summary
+
+Brief description of the change.
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature or command
+- [ ] Enhancement / improvement
+- [ ] Documentation update
+- [ ] Refactor
+- [ ] CI / pipeline change
+- [ ] Dependency update
+
+## Testing
+
+Describe how this was tested.
+
+- [ ] `just ci` passes locally (lint, format check, tests with coverage, Python 3.11, audit, build)
+- [ ] New behaviour is covered by tests that use the fakes, not the network or a real `az`
+- [ ] Tests sit in the directory that mirrors the code under test
+- [ ] If the Containerfile or its inputs changed: `just image`, `just image-slim` and
+      `just image-scan` pass
+- [ ] Manually run against a real tenant (say which commands)
+- [ ] GitHub Actions pipeline passed
+
+## Checklist
+
+- [ ] Code follows project conventions (see CONTRIBUTING.md)
+- [ ] `docs/` updated for any new command, option or exit code (and the README's table for a new group)
+- [ ] CHANGELOG.md updated
+- [ ] No tokens, tenant ids, subscription ids or real host names included (gitleaks checks)
+- [ ] No hard-coded tool names; they come from `core/brand.py` (the rebrand test checks)
+- [ ] Changes are scoped appropriately

libre_devops_helpers-0.4.1/.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

libre_devops_helpers-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,235 @@
+name: Lint and Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  # The release workflow calls this one, so the gate a release passes is this exact job
+  # set rather than a copy of it that can drift.
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  # github.workflow is the calling workflow's name under workflow_call, so a release and a
+  # push to main land in their own groups and do not cancel each other.
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  GITLEAKS_VERSION: 8.30.1
+  # From the release's checksums file. Dependabot cannot update a pinned download, so bump
+  # both together when moving to a new gitleaks release.
+  GITLEAKS_SHA256: 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+  PIP_AUDIT_VERSION: 2.10.1
+
+jobs:
+  secrets:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v7
+        with:
+          # Every commit, so a secret added and later removed is still found.
+          fetch-depth: 0
+
+      - name: Install gitleaks
+        run: |
+          archive="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          curl -sSfL -o "$RUNNER_TEMP/$archive" \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/$archive"
+          echo "${GITLEAKS_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
+          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" gitleaks
+
+      - name: Scan every commit
+        run: '"$RUNNER_TEMP/gitleaks" git --config .gitleaks.toml --redact --verbose .'
+
+  lint:
+    name: Lint and format check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+
+      # --locked fails the job when uv.lock is out of step with pyproject.toml.
+      - name: Install
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check --output-format=github src tests scripts
+
+      # Check only: formatting is fixed locally with 'just fmt', never in CI.
+      - name: Format check
+        run: uv run ruff format --check src tests scripts
+
+  audit:
+    name: Dependency audit (pip-audit)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      # The locked, hashed dependency tree, runtime and dev, exactly as CI installs it.
+      - name: Audit the locked dependencies for known vulnerabilities
+        run: |
+          uv export --frozen --all-extras --format requirements-txt --no-emit-project \
+            --output-file "$RUNNER_TEMP/requirements.txt"
+          uvx "pip-audit==${PIP_AUDIT_VERSION}" --strict --disable-pip --require-hashes \
+            --requirement "$RUNNER_TEMP/requirements.txt"
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        # The config path and file permission handling differ on Windows and macOS,
+        # so run the suite there too, on one Python version.
+        include:
+          - os: windows-latest
+            python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.13"
+
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --locked
+
+      # Includes the rebrand test, which renames a copy of the repository and runs its
+      # whole suite, so 'just rebrand' is proven on every platform.
+      - name: Test
+        run: uv run pytest
+
+  # Line and branch coverage on one platform, so the number is the same on every run.
+  # The floor (fail_under) lives in pyproject.toml, beside the rest of the coverage config.
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --locked
+
+      - name: Test with coverage
+        run: uv run pytest --cov --cov-report=term-missing --cov-report=xml
+
+      - name: Summarise
+        if: always()
+        shell: bash
+        run: |
+          if [ -f .coverage ]; then
+            {
+              echo "## Coverage"
+              echo
+              uv run coverage report --format=markdown --fail-under=0
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Keep the report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage
+          path: coverage.xml
+          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
+    timeout-minutes: 10
+    needs: [secrets, lint, audit, test, coverage]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      - name: Build the sdist and wheel
+        run: uv build
+
+      # Proves the wheel installs cleanly and the entry point resolves outside the source tree.
+      - name: Smoke test the wheel
+        shell: bash
+        run: |
+          uv venv "$RUNNER_TEMP/smoke"
+          uv pip install --python "$RUNNER_TEMP/smoke" dist/*.whl
+          "$RUNNER_TEMP/smoke/bin/ldo" --version
+          "$RUNNER_TEMP/smoke/bin/ldo" --help > /dev/null
+
+      # Built once here; a release publishes these exact files rather than rebuilding.
+      - name: Keep the build
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14

libre_devops_helpers-0.4.1/.github/workflows/codeql.yml

@@ -0,0 +1,46 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly full scan, Monday 03:00 UTC
+    - cron: '0 3 * * 1'
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  analyse:
+    name: Analyse (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # python: the package under src/ and the tests
+        # actions: the workflows themselves
+        language: [python, actions]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # Neither language is compiled, so there is nothing to build before analysis.
+      - name: Initialise CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: none
+          # security-and-quality catches both vulnerability patterns and bad practices
+          queries: security-and-quality
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: /language:${{ matrix.language }}