clauster 0.2.0__tar.gz

clauster-0.2.0/.bestpractices.json

@@ -0,0 +1,136 @@
+{
+  "description_good_status": "Met",
+  "description_good_justification": "Clauster's purpose and capabilities are described in the README and the GitHub repository description.",
+  "interact_status": "Met",
+  "interact_justification": "CONTRIBUTING.md explains how to interact and contribute; GitHub Issues are open. https://github.com/schubydoo/clauster/blob/main/CONTRIBUTING.md",
+  "contribution_status": "Met",
+  "contribution_justification": "The contribution process (branch + PR, CI gates) is documented. https://github.com/schubydoo/clauster/blob/main/CONTRIBUTING.md",
+  "contribution_requirements_status": "Met",
+  "contribution_requirements_justification": "CONTRIBUTING.md states the requirements: pytest with a 96% coverage gate, ruff/pyright/doc-lint, and Conventional Commit PR titles. https://github.com/schubydoo/clauster/blob/main/CONTRIBUTING.md",
+  "floss_license_status": "Met",
+  "floss_license_justification": "Released under the Apache License 2.0. https://github.com/schubydoo/clauster/blob/main/LICENSE",
+  "floss_license_osi_status": "Met",
+  "floss_license_osi_justification": "Apache-2.0 is an OSI-approved open source license.",
+  "license_location_status": "Met",
+  "license_location_justification": "License is in the standard top-level LICENSE file. https://github.com/schubydoo/clauster/blob/main/LICENSE",
+  "documentation_basics_status": "Met",
+  "documentation_basics_justification": "README documents installation, configuration (clauster.yml), and usage; CONTRIBUTING, SECURITY, UPGRADING, and THIRD_PARTY_NOTICES are also provided.",
+  "documentation_interface_status": "Met",
+  "documentation_interface_justification": "The README documents the external interface: the CLI subcommands (clauster run/doctor/backup/...) and the clauster.yml configuration keys; the web UI is self-describing.",
+  "sites_https_status": "Met",
+  "sites_https_justification": "The project homepage/repository (GitHub) and distribution channels (PyPI, GHCR) are all served over HTTPS.",
+  "discussion_status": "Met",
+  "discussion_justification": "GitHub Issues is enabled and used for project discussion. https://github.com/schubydoo/clauster/issues",
+  "english_status": "Met",
+  "english_justification": "All documentation and code comments are in English.",
+  "maintained_status": "Met",
+  "maintained_justification": "The project is actively maintained (frequent commits, PRs, and reviews).",
+  "repo_public_status": "Met",
+  "repo_public_justification": "Public git repository hosted on GitHub. https://github.com/schubydoo/clauster",
+  "repo_track_status": "Met",
+  "repo_track_justification": "Git tracks every change to the source, with full history.",
+  "repo_interim_status": "Met",
+  "repo_interim_justification": "Interim changes between releases are visible as commits/branches/PRs in git.",
+  "repo_distributed_status": "Met",
+  "repo_distributed_justification": "Git is a distributed version control system.",
+  "version_unique_status": "Met",
+  "version_unique_justification": "Each release has a unique Semantic Version identifier maintained in pyproject.toml and src/clauster/__init__.py, which makes every build uniquely identifiable. Release tagging is automated via release-please (.release-please-manifest.json / release-please-config.json) and produces a vX.Y.Z git tag when a release is published.",
+  "version_semver_status": "Met",
+  "version_semver_justification": "The project uses Semantic Versioning (MAJOR.MINOR.PATCH).",
+  "version_tags_status": "Unmet",
+  "version_tags_justification": "No release has been cut yet, so no semantic-version git tags exist. Tagging is configured and automated via release-please and will produce vX.Y.Z tags once the first release is published.",
+  "release_notes_status": "N/A",
+  "release_notes_justification": "No release has been published, so there are no release notes to provide. Releases are published through the release-please workflow, which generates human-readable, grouped release notes (a CHANGELOG entry and a tagged GitHub Release) from the Conventional Commit history.",
+  "release_notes_vulns_status": "N/A",
+  "release_notes_vulns_justification": "No release has shipped a security fix and no publicly-known vulnerability has required disclosure. When a release fixes one, release-please records it in the generated release notes (Bug Fixes section).",
+  "report_process_status": "Met",
+  "report_process_justification": "Bugs are reported via GitHub Issues; security issues via SECURITY.md. https://github.com/schubydoo/clauster/issues",
+  "report_tracker_status": "Met",
+  "report_tracker_justification": "GitHub Issues serves as the bug tracker. https://github.com/schubydoo/clauster/issues",
+  "report_responses_status": "Met",
+  "report_responses_justification": "The project is new and has received no external bug reports yet (the only open issue is the auto-generated Renovate dependency dashboard). The maintainer monitors the GitHub issue tracker; there is no backlog of unanswered reports.",
+  "enhancement_responses_status": "Met",
+  "enhancement_responses_justification": "No enhancement requests have been received yet (the only open issue is the auto-generated Renovate dependency dashboard). The maintainer monitors the GitHub issue tracker and responds to requests as they arrive.",
+  "report_archive_status": "Met",
+  "report_archive_justification": "GitHub Issues provides a public, persistent archive of reports and responses. https://github.com/schubydoo/clauster/issues",
+  "vulnerability_report_process_status": "Met",
+  "vulnerability_report_process_justification": "SECURITY.md documents the vulnerability reporting process. https://github.com/schubydoo/clauster/blob/main/SECURITY.md",
+  "vulnerability_report_private_status": "Met",
+  "vulnerability_report_private_justification": "Vulnerabilities are reported privately via GitHub private security advisories. https://github.com/schubydoo/clauster/security/advisories/new",
+  "vulnerability_report_response_status": "Met",
+  "vulnerability_report_response_justification": "SECURITY.md commits to an initial response within a few days.",
+  "build_status": "Met",
+  "build_justification": "Built from source with a standard PEP 517 build (uv + hatchling); installable via pip/uv as a wheel/sdist.",
+  "build_common_tools_status": "Met",
+  "build_common_tools_justification": "Built with common, widely available FLOSS tools (uv, hatchling, CPython).",
+  "build_floss_tools_status": "Met",
+  "build_floss_tools_justification": "All build tooling is FLOSS.",
+  "test_status": "Met",
+  "test_justification": "A pytest test suite covers the codebase (400+ tests).",
+  "test_invocation_status": "Met",
+  "test_invocation_justification": "Running the tests is documented in CONTRIBUTING.md (`uv run pytest`). https://github.com/schubydoo/clauster/blob/main/CONTRIBUTING.md",
+  "test_most_status": "Met",
+  "test_most_justification": "The suite covers ~96% of statements, enforced by a CI coverage gate.",
+  "test_continuous_integration_status": "Met",
+  "test_continuous_integration_justification": "GitHub Actions runs the suite on every PR across a Linux/macOS/Windows x Python 3.11-3.14 matrix.",
+  "test_policy_status": "Met",
+  "test_policy_justification": "CONTRIBUTING requires tests for new functionality, backed by the merge-blocking 96% coverage gate.",
+  "tests_are_added_status": "Met",
+  "tests_are_added_justification": "New functionality is added with tests; the coverage gate blocks merges that would drop coverage.",
+  "tests_documented_added_status": "Met",
+  "tests_documented_added_justification": "The test-and-coverage policy is documented in CONTRIBUTING.md.",
+  "warnings_status": "Met",
+  "warnings_justification": "ruff (broad ruleset including bugbear and flake8-bandit) and pyright run in CI.",
+  "warnings_fixed_status": "Met",
+  "warnings_fixed_justification": "CI fails on any ruff or pyright finding; warnings are not tolerated on main.",
+  "warnings_strict_status": "Met",
+  "warnings_strict_justification": "Lint and type checks are treated as errors (CI-blocking).",
+  "know_secure_design_status": "Met",
+  "know_secure_design_justification": "The design applies least-privilege, fail-closed liveness, loopback-by-default networking, SSRF guards on clone, and per-project trust gating (documented in SECURITY.md).",
+  "know_common_errors_status": "Met",
+  "know_common_errors_justification": "The code guards against common errors (input validation, SSRF protection, no shell=True/argv lists, output redaction); ruff-S (bandit) and CodeQL enforce this in CI.",
+  "crypto_published_status": "Met",
+  "crypto_published_justification": "Cryptography is limited to argon2id password hashing (argon2-cffi) and Python's `secrets` module; both are standard, published mechanisms.",
+  "crypto_call_status": "Met",
+  "crypto_call_justification": "The project calls the argon2-cffi library and Python's stdlib `secrets`; it implements no home-grown cryptography.",
+  "crypto_floss_status": "Met",
+  "crypto_floss_justification": "argon2-cffi and the Python standard library are FLOSS.",
+  "crypto_keylength_status": "Met",
+  "crypto_keylength_justification": "argon2id is used with the library's secure default cost parameters; generated secrets/tokens are 256-bit (`secrets.token_bytes(32)`).",
+  "crypto_working_status": "Met",
+  "crypto_working_justification": "No broken or risky algorithms are used for security; argon2id for passwords, no MD5/SHA-1 for security purposes.",
+  "crypto_weaknesses_status": "Met",
+  "crypto_weaknesses_justification": "No known-weak cryptographic algorithms are used.",
+  "crypto_pfs_status": "N/A",
+  "crypto_pfs_justification": "Clauster performs no network key agreement itself; TLS (and forward secrecy) is provided by the operator's reverse proxy. It binds to loopback by default.",
+  "crypto_password_storage_status": "Met",
+  "crypto_password_storage_justification": "Login passwords are stored only as argon2id hashes (salted, memory-hard KDF) via argon2-cffi; plaintext is never stored. Verification is constant-time.",
+  "crypto_random_status": "Met",
+  "crypto_random_justification": "Cryptographically secure randomness uses Python's `secrets` module (token_bytes/token_hex).",
+  "delivery_mitm_status": "Met",
+  "delivery_mitm_justification": "The software is delivered over HTTPS (GitHub, PyPI, GHCR) and its dependencies are version/hash pinned, preventing MITM during retrieval.",
+  "delivery_unsigned_status": "Met",
+  "delivery_unsigned_justification": "Installation instructions use HTTPS package managers (pip/uv, docker pull); users are never directed to download unsigned code over HTTP.",
+  "vulnerabilities_fixed_60_days_status": "Met",
+  "vulnerabilities_fixed_60_days_justification": "Renovate and GitHub security alerts surface dependency vulnerabilities, which are patched promptly (well within 60 days).",
+  "vulnerabilities_critical_fixed_status": "Met",
+  "vulnerabilities_critical_fixed_justification": "No known unpatched vulnerabilities exist (OpenSSF Scorecard Vulnerabilities check scores 10/10).",
+  "no_leaked_credentials_status": "Met",
+  "no_leaked_credentials_justification": "No credentials are stored in the repository; gitleaks and GitHub secret scanning run in CI, sensitive config is gitignored, and session URLs/tokens are redacted in logs.",
+  "static_analysis_status": "Met",
+  "static_analysis_justification": "Static analysis runs in CI: ruff (including flake8-bandit `S` security rules), pyright, CodeQL, and Trivy.",
+  "static_analysis_common_vulnerabilities_status": "Met",
+  "static_analysis_common_vulnerabilities_justification": "CodeQL and ruff-S specifically target common vulnerability patterns.",
+  "static_analysis_fixed_status": "Met",
+  "static_analysis_fixed_justification": "Static-analysis findings are merge-blocking and fixed before merge.",
+  "static_analysis_often_status": "Met",
+  "static_analysis_often_justification": "Static analysis runs on every PR and push (CodeQL also on a weekly schedule).",
+  "dynamic_analysis_status": "Unmet",
+  "dynamic_analysis_justification": "No dynamic analysis or fuzzing is currently run; the project relies on static analysis plus a high-coverage test suite. Python is memory-safe.",
+  "dynamic_analysis_unsafe_status": "N/A",
+  "dynamic_analysis_unsafe_justification": "The project is written in Python, a memory-safe language; memory/behavior sanitizers for memory-unsafe languages do not apply.",
+  "dynamic_analysis_enable_assertions_status": "Met",
+  "dynamic_analysis_enable_assertions_justification": "The pytest suite exercises the code with assertions enabled throughout.",
+  "dynamic_analysis_fixed_status": "N/A",
+  "dynamic_analysis_fixed_justification": "No dynamic analysis is performed (see dynamic_analysis), so there are no such findings to fix; static analysis and tests cover this."
+}

clauster-0.2.0/.coderabbit.yaml

@@ -0,0 +1,17 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+#
+# Docstrings: our gate is ruff's pydocstyle (D) rules, enforced on EVERY PR by the
+# "ruff + pyright" CI job (.github/workflows/lint.yml, `on: pull_request`). It
+# requires docstrings on all public modules/classes/functions (pep257 convention;
+# D105/D107 and tests/** are intentionally exempt — see pyproject.toml).
+#
+# CodeRabbit's separate docstring-coverage pre-merge check computes a raw
+# percentage that counts inner/nested helpers (preexec closures, signal handlers,
+# test fixtures) which our gate deliberately exempts, so it reports a misleadingly
+# low number against its 80% default. Defer to ruff D as the single source of
+# truth and turn the redundant check off rather than run two disagreeing gates.
+language: "en-US"
+reviews:
+  pre_merge_checks:
+    docstrings:
+      mode: "off"

clauster-0.2.0/.dockerignore

@@ -0,0 +1,29 @@
+# Keep the build context (and final image) lean: only pyproject/uv.lock/README/src
+# feed the build. Everything else is noise or must never ship.
+.git
+.github
+.venv
+**/__pycache__
+**/*.py[cod]
+.pytest_cache
+.ruff_cache
+.mypy_cache
+htmlcov
+.coverage*
+tests
+dist
+build
+*.spec
+scripts
+
+# Local config + internal notes (mirror .gitignore; never bake into an image)
+clauster.yml
+NOTES.md
+HANDOFF.md
+DEBUG_NOTES.md
+PLAN_*.md
+*_spec*.md
+v4-panel-findings.md
+.claude
+.gitnexus
+.logfire

clauster-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Code owners for Clauster — https://docs.github.com/articles/about-code-owners
+#
+# GitHub uses this to auto-request review from the owner on matching PRs.
+# Branch protection does not (yet) *require* code-owner review — as a solo
+# project there's no second reviewer to approve — but declaring ownership here
+# is good hygiene and makes required code-owner review a one-line switch if the
+# maintainer set grows.
+
+* @schubydoo

clauster-0.2.0/.github/settings.yml

@@ -0,0 +1,143 @@
+# Probot Settings (https://github.com/repository-settings/app)
+# Install the GitHub App on this repo to make settings declarative.
+# Note: the App requires `Administration: Read & write` permission on the repo
+# to apply branch protection rules.
+#
+# Borrowed from the schubydoo python+uv family (dump1090-exporter / dockerize2)
+# and adapted for clauster. Two known gotchas are preserved verbatim below:
+#   - enforce_admins / restrictions MUST be `null`, never `false`/`[]` (#923)
+#   - every bot-applied label MUST be declared or Probot deletes it (#386)
+
+repository:
+  name: clauster
+  description: >-
+    Your homelab's Claude Code launchpad. Self-hosted web UI that spawns &
+    manages remote-control bridges on a remote host from any browser or phone —
+    start/stop, spawn & permission modes, CLAUDE.md editor, git clone, live log
+    tail, cost tracking. Loopback by default; password/reverse-proxy auth. No
+    telemetry.
+  # Topics: GitHub slugs disallow spaces — a leading space after "comma+space"
+  # gets silently dropped. Folded scalar + bare commas => exactly `a,b,c`.
+  topics: >-
+    claude,claude-code,remote-control,self-hosted,homelab,fastapi,nas,dispatcher,python
+  homepage: https://github.com/schubydoo/clauster
+  has_issues: true
+  has_projects: false
+  has_wiki: false
+  has_downloads: true
+  default_branch: main
+  allow_squash_merge: true
+  allow_merge_commit: false
+  allow_rebase_merge: true
+  allow_auto_merge: true
+  delete_branch_on_merge: true
+  allow_update_branch: true
+  # Web-UI squash defaults. Both default to PR_TITLE / PR_BODY out of the box;
+  # we override:
+  #   - squash_merge_commit_title: COMMIT_OR_PR_TITLE — use the single commit's
+  #     subject when a PR has only one commit, fall back to PR title otherwise.
+  #     Avoids the "(#NN)" suffix duplication.
+  #   - squash_merge_commit_message: COMMIT_MESSAGES — concatenate the branch's
+  #     commit messages into the squash body, preserving hand-crafted commit
+  #     bodies (rationale + Co-Authored-By trailers) instead of the PR desc.
+  # merge_commit_* settings deliberately omitted — allow_merge_commit is false,
+  # so those settings are inert.
+  squash_merge_commit_title: COMMIT_OR_PR_TITLE
+  squash_merge_commit_message: COMMIT_MESSAGES
+
+# Labels managed declaratively by Probot. Every label any of our bots applies
+# MUST be listed here — Probot Settings has a long-running issue
+# (repository-settings/app#386) where it deletes labels that aren't declared,
+# and the family has watched it strip Renovate's `dependencies` and
+# release-please's `autorelease: *` labels off PRs in real time. Standard
+# GitHub-created labels (bug, enhancement, documentation, etc.) are left alone.
+labels:
+  # ---- Renovate ----
+  - name: dependencies
+    color: ededed
+    description: Renovate-opened dependency update PRs (and the dashboard issue)
+  - name: security
+    color: d93f0b
+    description: Security-related — Renovate vulnerability alerts use this
+  - name: vendored-assets
+    color: ededed
+    description: Renovate heads-up to re-vendor self-hosted front-end assets (manual dist update)
+
+  # ---- Release Please ----
+  # release-please-action applies these to its release PRs / tagged release
+  # commits. Without them declared, Probot strips them mid-release-flow.
+  - name: "autorelease: pending"
+    color: ededed
+    description: Release Please — release PR is open, awaiting merge
+  - name: "autorelease: tagged"
+    color: 0e8a16
+    description: Release Please — release PR is merged and the tag has been pushed
+  - name: "autorelease: snapshot"
+    color: 5319e7
+    description: Release Please — snapshot/prerelease (rare)
+
+branches:
+  - name: main
+    protection:
+      required_pull_request_reviews:
+        # Solo maintainer: 0 required approvals, but stale reviews are dismissed
+        # and conversations must resolve. Raise this once there are co-maintainers.
+        required_approving_review_count: 0
+        dismiss_stale_reviews: true
+        require_code_owner_reviews: false
+      required_status_checks:
+        # Context names must match the check-run names GitHub records exactly —
+        # that's each job's `name:` field, NOT "workflow / job". A check must
+        # also have run on the repo at least once before it can be required.
+        #
+        # GOTCHA (observed on clauster's first push): when this file ships in a
+        # repo's FIRST push, none of these contexts have reported yet, and the
+        # Settings App's branch-protection PUT is rejected wholesale — labels /
+        # description / merge settings still apply (different API calls), but
+        # protection silently does NOT. Fix: once every listed check has run
+        # once, re-push this file (a no-op edit is enough) to re-apply.
+        #
+        # Aggregator pattern (mirrors the family):
+        #  - `ci required checks passed`        — ci.yml aggregator (needs: tests, build)
+        #  - `security required checks passed`  — security.yml aggregator
+        #                                         (needs: changes, codeql, gitleaks,
+        #                                         trivy-fs, trivy-image, zizmor,
+        #                                         dependency-review)
+        #  - `conventional PR title`            — pr-title.yml (gates the squash subject
+        #                                         that Release Please parses)
+        #  - `lint`                             — lint.yml (ruff + pyright + the
+        #                                         Markdown/YAML doc-lint; we gate it,
+        #                                         the family leaves lint non-required).
+        #                                         Direct job name, so renaming that job
+        #                                         means updating this list too.
+        #
+        # `OSSF Scorecard` is intentionally NOT required: scorecard.yml only
+        # triggers on push + schedule + branch_protection_rule, so requiring it
+        # would leave every PR perpetually pending.
+        strict: true
+        contexts:
+          - "ci required checks passed"
+          - "security required checks passed"
+          - "conventional PR title"
+          - "lint"
+      # `true` enforces branch protection for admins too — OpenSSF Scorecard's
+      # Branch-Protection check rewards this. NB the Settings App rejects `false`
+      # here silently (repository-settings/app#923): use `null` to disable,
+      # `true` to enforce. Trade-off: this removes the admin-merge bypass we used
+      # for the job-rename in #66, so a future required-context change can't be
+      # force-merged the same way — revert to `null` if you need that escape hatch.
+      #
+      # ⚠️ CONFIRMED (A/B test, 2026-06-02): the Settings App does NOT apply this
+      # field on an already-protected branch. It reconciles other sections on push
+      # (security log: settings[bot] `repo.change_merge_setting`, probot/14.3.2) but
+      # leaves enforce_admins untouched — #70's null→true never took. Set it directly:
+      #   gh api --method POST repos/schubydoo/clauster/branches/main/protection/enforce_admins
+      # (DELETE to disable) and re-GET to verify. Keep this `true` so the desired
+      # state is still declared, but don't trust the App to apply it.
+      enforce_admins: true
+      required_linear_history: true
+      allow_force_pushes: false
+      allow_deletions: false
+      required_conversation_resolution: true
+      # Same `null`-vs-empty-array gotcha; explicit `null` for safety.
+      restrictions: null

clauster-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,167 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # --------------------------------------------------------------------
+  # Unit tests across the supported Python versions (Linux only — clauster
+  # targets a Linux/NAS host; psutil/proc + bridge management aren't
+  # exercised on macOS/Windows). The 96% coverage gate lives in
+  # pyproject [tool.pytest.ini_options] addopts (--cov-fail-under=96), so
+  # a bare `pytest` enforces it on every cell.
+  # --------------------------------------------------------------------
+  tests:
+    name: tests (${{ matrix.os }}, ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    # Ubuntu, macOS, and Windows are all required (spec target: tri-platform).
+    # macOS + Windows were brought green via a .cmd entrypoint for the test stubs
+    # plus cross-platform guards; they now block merges like Linux, so a future
+    # regression on any platform can't silently rot the way these 29 once did.
+    strategy:
+      fail-fast: false
+      # Spec target is Ubuntu + macOS + Windows (conductor_spec_v3 §"Ubuntu,
+      # macOS, Windows" + 4-runner PyInstaller matrix; psutil was chosen for
+      # cross-platform liveness). Full Python sweep on every OS (3 × 4 = 12
+      # cells) so a version-specific portability bug can't hide on an untested
+      # OS×version combo. Public repo → Actions minutes are free; cells run in
+      # parallel. Only Linux enforces the coverage gate (see the pytest step).
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      # Matrix values flow through env vars (not inlined into `run:`) so zizmor's
+      # template-injection analysis doesn't flag the shell blocks. The matrix is
+      # hard-coded above, not derived from any PR-controlled input. `shell: bash`
+      # keeps one script across all three runners (Git Bash ships on Windows).
+      - name: Set up Python ${{ matrix.python-version }}
+        shell: bash
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+        run: uv python install "$PYTHON_VERSION"
+      - name: Install
+        shell: bash
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+        run: uv sync --extra dev --python "$PYTHON_VERSION"
+      # Linux enforces the 96% coverage gate (pyproject addopts). macOS + Windows
+      # still REPORT coverage (term-missing, for visibility into platform-specific
+      # gaps) but don't gate on it — `--cov-fail-under=0` overrides the addopts
+      # threshold — since branches are inherently platform-specific (Linux jiffies
+      # procStart, Windows O_BINARY/WNOHANG guards) and no single OS reaches 96%.
+      - name: pytest
+        shell: bash
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+          RUNNER_OS: ${{ runner.os }}
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            uv run --python "$PYTHON_VERSION" pytest -q \
+              --cov-report=xml --junitxml=junit.xml -o junit_family=legacy
+          else
+            uv run --python "$PYTHON_VERSION" pytest -q --cov-fail-under=0
+          fi
+      # Upload coverage + test results to Codecov from a single Linux cell (the
+      # gate platform). Linux is where the 96% number is measured; macOS/Windows
+      # coverage is platform-partial by design (see the pytest step), so uploading
+      # them would only muddy the trend. Token-based upload (CODECOV_TOKEN secret)
+      # → no `id-token` permission needed. Both uploads are non-blocking: Codecov
+      # isn't a required check and upload flakiness must never fail CI
+      # (fail_ci_if_error: false). Both use `!cancelled()` so a FAILED pytest run
+      # still uploads — pytest writes coverage.xml/junit.xml before the gate check,
+      # so a coverage drop shows up in the Codecov trend precisely when it matters,
+      # and failed tests still feed Codecov's flaky-test analytics. Test results go
+      # through codecov-action with `report_type: test_results` (the standalone
+      # test-results-action is deprecated), so we pin a single action SHA.
+      - name: Upload coverage to Codecov
+        if: ${{ !cancelled() && runner.os == 'Linux' && matrix.python-version == '3.13' }}
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() && runner.os == 'Linux' && matrix.python-version == '3.13' }}
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: junit.xml
+          report_type: test_results
+          fail_ci_if_error: false
+
+  # --------------------------------------------------------------------
+  # Build sdist + wheel. Cheap; runs on every push and PR so we always
+  # know the package is shippable.
+  # --------------------------------------------------------------------
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Build
+        run: uv build
+      - name: Upload dist artefacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+          if-no-files-found: error
+
+  # --------------------------------------------------------------------
+  # Required-checks aggregator. ONE check for branch protection to gate
+  # on, regardless of how many underlying jobs exist. `if: always()` so it
+  # runs even when a need failed; jq fails the aggregator iff any listed
+  # job is not success-or-skipped. Add a new ci.yml job by appending to
+  # `needs:` — branch protection lists only this one name.
+  # --------------------------------------------------------------------
+  ci-required-checks-passed:
+    name: ci required checks passed
+    if: always()
+    needs:
+      - tests
+      - build
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Check required jobs passed
+        env:
+          NEEDS_JSON: ${{ toJSON(needs) }}
+        run: |
+          failing=$(echo "$NEEDS_JSON" | jq -r '
+            to_entries[]
+            | select(.value.result != "success" and .value.result != "skipped")
+            | "\(.key): \(.value.result)"
+          ')
+          if [ -n "$failing" ]; then
+            echo "Failed or cancelled jobs:"
+            echo "$failing"
+            exit 1
+          fi
+          echo "All required jobs passed (or were intentionally skipped)."

clauster-0.2.0/.github/workflows/lint.yml

@@ -0,0 +1,55 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lint-${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    # This job name is a REQUIRED status check — it must match the context list
+    # in .github/settings.yml exactly (renaming means updating that list too).
+    # Runs ruff (check + format), pyright, and the Markdown + YAML doc-lint
+    # (scripts/lint-docs.sh).
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Install
+        run: uv sync --extra dev --python 3.13
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format --check
+        run: uv run ruff format --check .
+      - name: pyright
+        run: uv run pyright src/clauster
+      # Node for markdownlint-cli2: pin the runtime (ubuntu-latest's bundled Node
+      # drifts across image refreshes) and install the version-pinned, integrity-
+      # checked package from the lockfile via `npm ci`. yamllint comes from
+      # `uv sync --extra dev` above.
+      - name: Set up Node 20
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "20"
+          cache: npm
+      - name: Install Node deps
+        run: npm ci
+      # Markdown + YAML lint — the same script developers run locally.
+      - name: markdown + yaml lint
+        run: bash scripts/lint-docs.sh

clauster-0.2.0/.github/workflows/pr-title.yml

@@ -0,0 +1,41 @@
+name: PR Title
+
+# Validate that the pull-request title follows Conventional Commits. Because the
+# repo squash-merges, the PR title becomes the squashed commit subject — which
+# release-please parses to decide version bumps and CHANGELOG sections.
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pr-title-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: conventional PR title
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            revert
+            docs
+            chore
+            ci
+            build
+            test
+            refactor
+            style