refrain 0.1.3__tar.gz

refrain-0.1.3/.editorconfig

@@ -0,0 +1,29 @@
+# https://editorconfig.org — picked up automatically by VS Code, JetBrains,
+# Sublime, Vim/Neovim (with plugin), and most other editors. Keeps the
+# project consistent regardless of contributor local settings.
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Python: 4-space indent, soft 100-col guideline (matches Ruff defaults)
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+# Configs, docs, web assets: 2-space indent
+[*.{svg,yml,yaml,toml,json,desktop}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+# Markdown allows two trailing spaces as a hard line-break
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 2

refrain-0.1.3/.gitattributes

@@ -0,0 +1,24 @@
+# Normalize line endings across platforms — every text file gets LF.
+# Without this, Windows contributors would silently inject CRLF.
+
+* text=auto eol=lf
+
+# Explicit text declarations for common project files
+*.py     text eol=lf diff=python
+*.svg    text eol=lf
+*.yml    text eol=lf
+*.yaml   text eol=lf
+*.toml   text eol=lf
+*.md     text eol=lf
+*.sh     text eol=lf
+*.desktop text eol=lf
+.gitignore   text eol=lf
+.gitattributes text eol=lf
+.editorconfig  text eol=lf
+
+# Binary files — never normalize
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary

refrain-0.1.3/.github/FUNDING.yml

@@ -0,0 +1,9 @@
+# Optional sponsoring buttons — uncomment any line you actually want to
+# accept money on. Leaving the file in place but empty (with no
+# uncommented entries) is harmless: GitHub simply doesn't render the
+# Sponsor button.
+
+# github: Rockykln
+# ko_fi: Rockykln
+# liberapay: Rockykln
+# custom: ['https://www.paypal.me/Rockykln']

refrain-0.1.3/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,82 @@
+name: Bug report
+description: Something is broken or behaves unexpectedly
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. The more concrete you can be,
+        the faster we can fix it.
+
+  - type: input
+    id: version
+    attributes:
+      label: Refrain version
+      description: Run `refrain --version` or check the bottom-right of the settings window.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: distro
+    attributes:
+      label: Distribution + desktop
+      placeholder: "Arch Linux + KDE Plasma 6.2 (Wayland)"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.7"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: source
+    attributes:
+      label: Playback source
+      options:
+        - Apple Music Web (browser)
+        - Bluetooth (AVRCP)
+        - Both
+        - Not sure
+    validations:
+      required: true
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser (if Apple Music Web)
+      placeholder: "Firefox 134, Zen 1.7, Chromium …"
+    validations:
+      required: false
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you do, what did you expect, what did you get instead?
+    validations:
+      required: true
+
+  - 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.
+      render: shell
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirmation
+      options:
+        - label: I searched existing issues before opening this one.
+          required: true

refrain-0.1.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+# Force users into the templates — no blank "issue" without a category.
+blank_issues_enabled: false
+
+contact_links:
+  - name: Security report (private)
+    url: https://github.com/Rockykln/refrain/security/advisories/new
+    about: For vulnerabilities, please use private reporting (or email report@rockykln.com).
+  - name: General questions / feedback
+    url: mailto:contact@rockykln.com
+    about: For non-bug, non-vulnerability questions — feature ideas, packaging help, etc.

refrain-0.1.3/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,58 @@
+name: Feature request
+description: Suggest a new feature or enhancement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Refrain stays focused: it's a Discord Rich Presence app for Apple
+        Music on Linux. Features that fit that scope are very welcome.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What can't you do today, or what's awkward?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like it to work? UI sketches and config shapes welcome.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about + why you didn't pick them.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - Source (MPRIS / Bluetooth / something else)
+        - Discord status (cover art, buttons, layout)
+        - Settings UI
+        - Notifications / tray
+        - Distribution (Flatpak / AUR / AppImage / …)
+        - Documentation
+        - Something else
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirmation
+      options:
+        - label: I searched existing issues before opening this one.
+          required: true
+        - label: I'm willing to discuss design tradeoffs (this is not a "fire and forget").
+          required: false

refrain-0.1.3/.github/codeql/codeql-config.yml

@@ -0,0 +1,30 @@
+name: refrain CodeQL config
+
+# We run the security-and-quality query suite. The "security" half is what
+# we care about; the "quality" half ships notes for stylistic patterns that
+# are intentional in this codebase. Suppress those so the alerts page
+# surfaces real findings, not background noise.
+
+queries:
+  - uses: security-and-quality
+
+query-filters:
+  # Empty `except` blocks are deliberate in best-effort 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.
+  - exclude:
+      id: py/empty-except
+
+  # `_qt_bridge` is a module-level memo for `attach_qt_log_bridge()` so
+  # repeat calls return the same QObject. CodeQL's per-function analysis
+  # mistakes the cross-call read for "unused". The pattern is
+  # idiomatic for one-shot lazy initializers.
+  - exclude:
+      id: py/unused-global-variable
+
+paths-ignore:
+  - tests/**
+  - reference/**
+  - assets/**
+  - docs/**

refrain-0.1.3/.github/dependabot.yml

@@ -0,0 +1,44 @@
+version: 2
+
+updates:
+  # Python dependencies (pip — reads requirements*.txt + pyproject.toml)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+    groups:
+      qt:
+        patterns:
+          - "PySide6*"
+          - "shiboken6*"
+      runtime:
+        patterns:
+          - "pypresence"
+          - "dbus-python"
+      dev-tools:
+        patterns:
+          - "pytest*"
+          - "coverage"
+          - "ruff"
+          - "bandit"
+          - "pip-audit"
+
+  # GitHub Actions used in workflows
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "ci"

refrain-0.1.3/.github/pull_request_template.md

@@ -0,0 +1,45 @@
+<!--
+Thanks for the PR! A few quick checks before merging — fill in
+whatever's relevant and delete the rest.
+-->
+
+## Summary
+
+<!-- One or two sentences. What does this change and why? -->
+
+## Type
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / cleanup (no behavior change)
+- [ ] Documentation
+- [ ] CI / tooling
+- [ ] Other:
+
+## Linked issues
+
+<!-- e.g. Closes #12, Refs #34 -->
+
+## Tested on
+
+<!-- Which distro / desktop did you actually run this on? Tick what applies. -->
+
+- [ ] KDE Plasma 6 (Wayland)
+- [ ] KDE Plasma 6 (X11)
+- [ ] GNOME (with AppIndicator extension)
+- [ ] Other DE (specify):
+- [ ] Apple Music Web playback verified
+- [ ] Bluetooth (AVRCP) playback verified
+- [ ] Discord RPC visible in profile
+
+## Checklist
+
+- [ ] `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)
+- [ ] No new private data leaks into the repo (no real Discord client IDs other than the project's, no MAC addresses, no tokens)
+- [ ] If user-visible strings changed, they're English
+- [ ] If the version was bumped, both `pyproject.toml` and `src/refrain/__init__.py` match
+- [ ] README / CHANGELOG updated if behavior changed
+
+## Screenshots (UI changes only)

refrain-0.1.3/.github/workflows/codeql.yml

@@ -0,0 +1,41 @@
+name: codeql
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  schedule:
+    # Weekly scheduled scan picks up newly disclosed vulnerabilities
+    - cron: "27 4 * * 1"
+
+jobs:
+  analyze:
+    name: analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    # Skip on private repos — Code Scanning needs GitHub Advanced Security
+    # to ingest the SARIF results, which isn't free for private repos.
+    if: github.event.repository.visibility == 'public'
+    permissions:
+      actions:        read
+      contents:       read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          config-file: ./.github/codeql/codeql-config.yml
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

refrain-0.1.3/.github/workflows/release.yml

@@ -0,0 +1,125 @@
+name: release
+
+# Triggered when a semver tag is pushed: e.g. `git tag v0.2.0 && git push --tags`
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write   # required to create the release
+  id-token: write   # required by PyPA Trusted Publishers (OIDC) for PyPI upload
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/refrain/
+
+    steps:
+      - name: Checkout (full history for changelog)
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install + run tests (gate the release)
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-cov
+          PYTHONPATH=src pytest -q
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          INIT_VERSION=$(python -c "import sys; sys.path.insert(0,'src'); import refrain; print(refrain.__version__)")
+          PYPROJECT_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$INIT_VERSION" ] || [ "$TAG" != "$PYPROJECT_VERSION" ]; then
+            echo "::error::Version mismatch — tag=v$TAG, __init__.py=$INIT_VERSION, pyproject.toml=$PYPROJECT_VERSION"
+            exit 1
+          fi
+          echo "Releasing v$TAG"
+
+      - name: Verify CHANGELOG has a matching entry for this tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          if ! grep -qE "^## \[${TAG}\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md is missing a '## [${TAG}]' section"
+            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.
+          mkdir -p pypi-dist
+          cp dist/*.whl dist/*.tar.gz pypi-dist/
+          ls -la pypi-dist/
+
+      # 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.
+      - 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 \
+            zsync appstream patchelf squashfs-tools file
+          pip install appimage-builder
+
+      - 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
+          # output filename (Refrain-<version>-x86_64.AppImage). Rewrite it
+          # to match the tag so we don't hand-edit the recipe per release.
+          sed -i -E "s/^(    version: ).*/\1${TAG}/" packaging/appimage/AppImageBuilder.yml
+          grep "    version:" packaging/appimage/AppImageBuilder.yml
+          cd packaging/appimage
+          appimage-builder --recipe AppImageBuilder.yml --skip-test
+          mkdir -p ../../dist
+          mv *.AppImage ../../dist/ 2>/dev/null || true
+          mv *.AppImage.zsync ../../dist/ 2>/dev/null || true
+          ls -la ../../dist/
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref, '-') }}   # e.g. v0.2.0-rc1
+          name: "Refrain ${{ github.ref_name }}"
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/*.AppImage
+            dist/*.AppImage.zsync
+
+      # PyPI upload via Trusted Publishers (OIDC). No API token needed; the
+      # one-time setup is on pypi.org → Manage → Publishing → Add a new
+      # pending publisher (project: refrain, owner: Rockykln,
+      # repository: refrain, workflow: release.yml, environment: pypi).
+      # 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
+        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.1.3/.github/workflows/security.yml

@@ -0,0 +1,86 @@
+name: security
+
+# Defense-in-depth scanners on top of CodeQL + Dependabot:
+#   - bandit     : Python-specific SAST (catches idioms CodeQL sometimes misses)
+#   - pip-audit  : OSV-backed dependency CVE scan
+#   - trufflehog : verified-secret detection across the full git history
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: "31 5 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+
+  bandit:
+    name: bandit (python SAST)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install bandit
+        run: pip install bandit
+
+      - name: Run bandit (medium + high severity only)
+        # Config (skips, exclude_dirs) lives in pyproject.toml [tool.bandit].
+        # -ll = report only Medium and High severity issues; lows are noise.
+        run: bandit -c pyproject.toml -r src/refrain -ll
+
+  pip-audit:
+    name: pip-audit (dependency CVEs)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install system headers for dbus-python build
+        # dbus-python is a C-extension module; pip-audit's resolver tries
+        # to build it during dependency resolution, which needs libdbus's
+        # development headers + glib. Without these the audit job fails
+        # not on a CVE but on a build error.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libdbus-1-dev libglib2.0-dev pkg-config
+
+      - name: Install pip-audit
+        run: |
+          python -m pip install --upgrade pip
+          pip install pip-audit
+
+      - name: Run pip-audit on requirements.txt
+        # --strict makes the job fail on any known vulnerability in the
+        # declared dependency set. Refrain has only three runtime deps, so
+        # noise is minimal.
+        run: pip-audit -r requirements.txt --strict
+
+  trufflehog:
+    name: trufflehog (secret detection)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Run TruffleHog
+        uses: trufflesecurity/trufflehog@17456f8c7d042d8c82c9a8ca9e937231f9f42e26  # v3.95.2
+        with:
+          # --only-verified: a secret only counts as flagged when TruffleHog
+          # successfully validates it against the live service. Drops the
+          # false-positive rate dramatically.
+          extra_args: --only-verified

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

@@ -0,0 +1,59 @@
+name: tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install test dependencies
+        # Tests are designed not to require PySide6 / dbus-python / pypresence,
+        # so the heavy runtime deps don't need to be installed in CI. The
+        # modules that do depend on them are syntax-checked in the compile step.
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-cov
+
+      - name: Compile-check every module
+        # Catches syntax errors in modules tests don't import (daemon, ui/*, sources/mpris, sources/bluetooth)
+        run: python -m compileall -q src/
+
+      - name: Run tests with coverage
+        run: PYTHONPATH=src pytest --cov --cov-report=term-missing
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint with ruff
+        run: ruff check . --output-format=github
+        continue-on-error: true   # warning only — don't fail PRs on style alone
+
+      - name: Format check with ruff
+        run: ruff format --check .
+        continue-on-error: true