refrain 0.5.2__tar.gz → 0.5.3__tar.gz

{refrain-0.5.2 → refrain-0.5.3}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: Refrain version
       description: Run `refrain --version` or check the bottom-right of the settings window.
-      placeholder: "0.5.2"
+      placeholder: "0.5.3"
     validations:
       required: true
 
@@ -61,14 +61,23 @@ body:
     validations:
       required: true
 
+  - type: markdown
+    attributes:
+      value: |
+        **Before you paste a log:** issues are public. The log lists the songs you
+        played (your listening history) and, in debug mode, the address of your
+        Bluetooth device. Read it first and remove anything you don't want public,
+        or mail the log to [contact@rockykln.com](mailto:contact@rockykln.com) instead
+        and mention your issue number.
+
   - type: textarea
     id: logs
     attributes:
       label: Refrain log
       description: |
         Paste the relevant portion of `~/.local/state/refrain/refrain.log`.
-        Tracks playing at the time of the bug are useful context but no secrets
-        live in the log.
+        It holds no passwords or tokens, but it does contain song titles and,
+        in debug mode, Bluetooth device addresses — check it before posting.
       render: shell
     validations:
       required: false

{refrain-0.5.2 → refrain-0.5.3}/.github/codeql/codeql-config.yml

@@ -9,7 +9,7 @@ queries:
   - uses: security-and-quality
 
 query-filters:
-  # Empty `except` blocks are deliberate in best-effort cleanup paths
+  # Empty `except` blocks are deliberate in cleanup paths
   # (DBus disconnects, Discord IPC, tray icon teardown). Each site has
   # context in surrounding code; the CodeQL note here would be repeated
   # ~10× without adding signal.

{refrain-0.5.2 → refrain-0.5.3}/.github/pull_request_template.md

@@ -34,6 +34,7 @@ whatever's relevant and delete the rest.
 
 ## Checklist
 
+- [ ] I agree that my contribution is licensed as described in the "Contributions" section of LICENSE (summary in CONTRIBUTING.md)
 - [ ] `pytest` passes locally
 - [ ] `ruff check .` and `ruff format --check .` are clean
 - [ ] New / changed behavior is covered by tests (or unreachable from tests due to system integration — explain)

{refrain-0.5.2 → refrain-0.5.3}/.github/workflows/codeql.yml

@@ -27,15 +27,15 @@ jobs:
         language: [python]
 
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd  # v4.38.1
         with:
           languages: ${{ matrix.language }}
           config-file: ./.github/codeql/codeql-config.yml
 
       - name: Perform CodeQL analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd  # v4.38.1
         with:
           category: "/language:${{ matrix.language }}"

{refrain-0.5.2 → refrain-0.5.3}/.github/workflows/release.yml

@@ -6,31 +6,30 @@ on:
     tags:
       - "v*.*.*"
 
+# The AppImage build tools are installed unpinned, so the job that runs them
+# only gets read access; the write and OIDC permissions sit on the small
+# attestation and publishing jobs below.
 permissions:
-  contents: write   # required to create the release
-  id-token: write   # required by PyPA Trusted Publishers (OIDC) for PyPI upload
+  contents: read
 
 jobs:
-  release:
-    runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/project/refrain/
+  build:
+    runs-on: ubuntu-24.04
 
     steps:
       - name: Checkout (full history for changelog)
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: "3.12"
           cache: pip
+          cache-dependency-path: requirements-dev.lock
 
       - name: Install + run tests (gate the release)
         run: |
-          python -m pip install --upgrade pip
           # System libs: dbus-python needs the *-dev headers at build
           # time; PySide6.QtWidgets needs the EGL/xkbcommon/GL/fontconfig
           # runtime libs to import (even under QT_QPA_PLATFORM=offscreen).
@@ -38,10 +37,10 @@ jobs:
           sudo apt-get install -y \
             libdbus-1-dev libglib2.0-dev pkg-config \
             libegl1 libxkbcommon0 libfontconfig1 libgl1
-          # Install the package itself so the test imports get every
-          # runtime dep (PySide6, pypresence, dbus-python) — without
-          # this the new test_daemon_*.py files fail at collection.
-          pip install -e ".[dev]"
+          # The pinned, hash-checked tool and runtime versions, then
+          # Refrain itself on top.
+          pip install --require-hashes -r requirements-dev.lock
+          pip install --no-deps -e .
           pytest -q
 
       - name: Verify tag matches package version
@@ -64,7 +63,7 @@ jobs:
           fi
 
       - name: Verify Flatpak manifest pins this tag
-        # The Flatpak build source is a pinned (tag, commit) — it isn't
+        # The Flatpak build source is a pinned tag — it isn't
         # rebuilt/published by this workflow (no live Flathub channel),
         # so nothing else catches it going stale. It silently sat on
         # v0.1.4 from then until v0.4.2. This gate makes a stale pin a
@@ -76,14 +75,9 @@ jobs:
             echo "::error::$MANIFEST is not pinned to tag v${TAG}"
             exit 1
           fi
-          if ! grep -qE "^        commit: [0-9a-f]{40}$" "$MANIFEST"; then
-            echo "::error::$MANIFEST has no valid 40-character commit pin"
-            exit 1
-          fi
 
       - name: Build wheel + sdist
         run: |
-          pip install build
           python -m build
           # Keep a clean copy of just the Python distributions for PyPI;
           # the AppImage step writes additional files into dist/ later.
@@ -93,21 +87,19 @@ jobs:
 
       # Single-file AppImage so end users can grab one binary from the
       # Releases page and run it without installing anything else.
-      # Marked continue-on-error so a recipe glitch never blocks shipping
-      # the wheel + sdist; we re-attempt by deleting + re-pushing the tag.
+      # The recipe installs Refrain with the runner's /usr/bin/python3,
+      # which must match the Python it bundles from Ubuntu 24.04.
       - name: Install AppImage build deps
-        continue-on-error: true
         run: |
           sudo apt-get update
           sudo apt-get install -y \
-            libdbus-1-dev libglib2.0-dev pkg-config \
-            libfuse2 desktop-file-utils \
+            python3-pip libfuse2t64 desktop-file-utils \
             zsync appstream patchelf squashfs-tools file
-          pip install appimage-builder
+          # appimage-builder can't parse Ubuntu package versions with newer packaging.
+          pip install appimage-builder "packaging<22"
 
       - name: Build AppImage
         id: appimage
-        continue-on-error: true
         run: |
           TAG="${GITHUB_REF#refs/tags/v}"
           # The recipe pins a literal `version:` value, which determines the
@@ -122,6 +114,44 @@ jobs:
           mv *.AppImage.zsync ../../dist/ 2>/dev/null || true
           ls -la ../../dist/
 
+      # Every AppImage up to 0.5.2 was published without ever starting.
+      - name: Start the AppImage once
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          out="$(./dist/Refrain-${TAG}-x86_64.AppImage --appimage-extract-and-run --version)"
+          echo "$out"
+          [ "$out" = "refrain ${TAG}" ]
+
+      - name: Check licence notices and Qt modules in the AppImage
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          tmp="$(mktemp -d)"
+          (cd "$tmp" && "$GITHUB_WORKSPACE/dist/Refrain-${TAG}-x86_64.AppImage" --appimage-extract >/dev/null)
+          doc="$tmp/squashfs-root/usr/share/doc/refrain"
+          grep -q "^  PySide6_Essentials " "$doc/THIRD-PARTY-NOTICES"
+          grep -q "^  python3.12 " "$doc/THIRD-PARTY-NOTICES"
+          test -s "$doc/LICENSE" && test -s "$doc/LICENSES/LGPL-3" && test -s "$doc/LICENSES/GPL-3"
+          gpl_only="$(find "$tmp/squashfs-root" -iregex '.*\(Lottie\|WaylandCompositor\|VirtualKeyboard\|Charts\|DataVisualization\|Quick3D\|pyside6_addons\).*')"
+          if [ -n "$gpl_only" ]; then
+            echo "::error::GPL-only Qt parts in the AppImage:"; echo "$gpl_only"; exit 1
+          fi
+          rm -rf "$tmp"
+
+      # The in-app updater only installs an AppImage listed here, and only once
+      # the owner has signed this file (SHA256SUMS.sig, see packaging/README.md).
+      - name: Checksums for the in-app updater
+        run: |
+          cd dist
+          sha256sum *.AppImage > SHA256SUMS
+          cat SHA256SUMS
+
+      - name: Publish the AppImage's third-party notices next to it
+        run: |
+          cd dist
+          ./Refrain-*-x86_64.AppImage --appimage-extract usr/share/doc/refrain/THIRD-PARTY-NOTICES > /dev/null
+          mv squashfs-root/usr/share/doc/refrain/THIRD-PARTY-NOTICES .
+          rm -rf squashfs-root
+
       # Extract the matching `## [X.Y.Z]` section from CHANGELOG.md
       # and feed it into the GitHub release body. Without this we'd
       # fall back to GitHub's auto-generated "Full Changelog: …"
@@ -145,16 +175,79 @@ jobs:
             echo "::error::CHANGELOG section for v${TAG} extracted to nothing"
             exit 1
           fi
+          cat >> release-notes.md <<'NOTES'
+
+          ---
+
+          The AppImage bundles third-party software under its own licences; the
+          list, with versions and where to get the source, is in `THIRD-PARTY-NOTICES`
+          below and inside the AppImage. Versions that were taken down, and why, are
+          listed in [docs/releases.md](https://github.com/Rockykln/refrain/blob/main/docs/releases.md).
+          NOTES
+
+      - name: Hand the release files to the publishing jobs
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: release
+          path: |
+            dist/
+            release-notes.md
+          if-no-files-found: error
+
+      - name: Hand the PyPI files to the publishing job
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: pypi-dist
+          path: pypi-dist/
+          if-no-files-found: error
+
+  attest:
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write       # Sigstore signing certificate for the attestation
+      attestations: write   # store the attestation with the repository
+
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: release
+
+      # Verify with: gh attestation verify <file> --repo Rockykln/refrain
+      - name: Attest build provenance of the release files
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
+        with:
+          subject-path: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/*.AppImage
+            dist/*.AppImage.zsync
+            dist/SHA256SUMS
+            dist/THIRD-PARTY-NOTICES
 
-      - name: Create GitHub release
-        uses: softprops/action-gh-release@v3
+  github-release:
+    needs: [build, attest]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write   # required to create the release
+
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: release
+
+      # A draft: the owner signs SHA256SUMS on their own machine and only then
+      # publishes it (packaging/release_key.py release <tag>).
+      - name: Create GitHub release (draft)
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64  # v3.0.3
         with:
           # Use our CHANGELOG section (extracted above), not GitHub's
           # auto-generated notes — the in-app update dialog renders
           # this body verbatim so it has to actually be the changelog.
           body_path: release-notes.md
           generate_release_notes: false
-          draft: false
+          draft: true
           prerelease: ${{ contains(github.ref, '-') }}   # e.g. v0.2.0-rc1
           name: "Refrain ${{ github.ref_name }}"
           files: |
@@ -162,6 +255,24 @@ jobs:
             dist/*.tar.gz
             dist/*.AppImage
             dist/*.AppImage.zsync
+            dist/SHA256SUMS
+            dist/THIRD-PARTY-NOTICES
+
+  pypi:
+    # After the GitHub release, as before the jobs were split.
+    needs: github-release
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/project/refrain/
+    permissions:
+      id-token: write   # required by PyPA Trusted Publishers (OIDC) for PyPI upload
+
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: pypi-dist
+          path: pypi-dist/
 
       # PyPI upload via Trusted Publishers (OIDC). No API token needed; the
       # one-time setup is on pypi.org → Manage → Publishing → Add a new
@@ -170,12 +281,9 @@ jobs:
       # Skips silently if the version already exists on PyPI so re-running
       # a release for AppImage-only fixes doesn't fail the workflow.
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
         with:
           packages-dir: pypi-dist/
           skip-existing: true
           verbose: true
           attestations: true
-        # Don't let an upload hiccup wipe out the GitHub release that
-        # already succeeded above — reruns can fix PyPI later.
-        continue-on-error: true

{refrain-0.5.2 → refrain-0.5.3}/.github/workflows/security.yml

@@ -15,7 +15,6 @@ on:
 
 permissions:
   contents: read
-  security-events: write
 
 jobs:
 
@@ -23,15 +22,16 @@ jobs:
     name: bandit (python SAST)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      - uses: actions/setup-python@v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: "3.12"
           cache: pip
+          cache-dependency-path: requirements-dev.lock
 
       - name: Install bandit
-        run: pip install bandit
+        run: pip install --require-hashes -c requirements-dev.lock bandit
 
       - name: Run bandit (medium + high severity only)
         # Config (skips, exclude_dirs) lives in pyproject.toml [tool.bandit].
@@ -42,12 +42,13 @@ jobs:
     name: pip-audit (dependency CVEs)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      - uses: actions/setup-python@v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: "3.12"
           cache: pip
+          cache-dependency-path: requirements-dev.lock
 
       - name: Install system headers for dbus-python build
         # dbus-python is a C-extension module; pip-audit's resolver tries
@@ -60,8 +61,7 @@ jobs:
 
       - name: Install pip-audit
         run: |
-          python -m pip install --upgrade pip
-          pip install pip-audit
+          pip install --require-hashes -c requirements-dev.lock pip-audit
 
       - name: Run pip-audit on requirements.txt
         # --strict makes the job fail on any known vulnerability in the
@@ -69,11 +69,16 @@ jobs:
         # noise is minimal.
         run: pip-audit -r requirements.txt --strict
 
+      - name: Run pip-audit on the pinned dev/CI lock
+        # Nothing updates requirements-dev.lock on its own; a finding here
+        # means: regenerate it (command at the top of the file).
+        run: pip-audit -r requirements-dev.lock --require-hashes --disable-pip --strict
+
   trufflehog:
     name: trufflehog (secret detection)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
 

refrain-0.5.3/.github/workflows/tests.yml

@@ -0,0 +1,106 @@
+name: tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: requirements-dev.lock
+
+      - name: Install runtime + test dependencies
+        # The newer tests import refrain modules that pull PySide6 /
+        # pypresence / dbus-python at module load, so the runtime deps
+        # have to be present in CI too. PySide6.QtWidgets requires the
+        # EGL / xkbcommon / GL / fontconfig system libs even when run
+        # under QT_QPA_PLATFORM=offscreen — without them the import
+        # itself fails before the test can opt out.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libdbus-1-dev libglib2.0-dev pkg-config \
+            libegl1 libxkbcommon0 libfontconfig1 libgl1
+          pip install --require-hashes -r requirements-dev.lock
+          pip install --no-deps -e .
+
+      - name: Compile-check every module
+        run: python -m compileall -q src/
+
+      - name: Run tests with coverage
+        run: PYTHONPATH=src pytest --cov --cov-report=term-missing --cov-fail-under=99
+
+      - name: Coverage in the job summary
+        if: ${{ !cancelled() && hashFiles('.coverage') != '' }}
+        run: |
+          {
+            echo "### Coverage (Python ${{ matrix.python-version }}): $(coverage report --format=total)%"
+            echo
+            coverage report --format=markdown
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  lowest:
+    # The lower bounds in pyproject.toml, on the oldest supported Python.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            requirements-dev.lock
+            requirements-lowest.txt
+
+      - name: Install the oldest supported dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libdbus-1-dev libglib2.0-dev pkg-config \
+            libegl1 libxkbcommon0 libfontconfig1 libgl1
+          pip install --require-hashes -c requirements-dev.lock pytest
+          pip install -r requirements-lowest.txt
+          pip install --no-deps -e .
+          pip check
+
+      - name: Run tests
+        run: PYTHONPATH=src pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-dev.lock
+
+      - name: Install ruff
+        # The version comes from requirements-dev.lock, like everywhere else.
+        run: pip install --require-hashes -c requirements-dev.lock ruff
+
+      - name: Lint with ruff
+        run: ruff check . --output-format=github
+
+      - name: Format check with ruff
+        run: ruff format --check .