haggle

SECURITY.md section Supported Versions states the latest tagged release on main is the only supported version, with upgrades surfaced to users automatically via HACS. The README's "Rollback / downgrade" section (https://github.com/NaanyaBiz/haggle/blob/main/README.md) documents that any prior release can be reinstalled via HACS, that config entries are downgrade-safe and statistics survive in both directions, and docs/releasing.md requires a recorded manual downgrade test with each stable release.

The project tracks individual issues on the GitHub issue tracker at https://github.com/NaanyaBiz/haggle/issues, declared machine-readably in the integration manifest ("issue_tracker" in https://github.com/NaanyaBiz/haggle/blob/main/custom_components/haggle/manifest.json) and in pyproject.toml project URLs. CONTRIBUTING.md requires an issue-first workflow and AGENTS.md defines a triaged label taxonomy (P1-P3 priority, sev:high/med/low, escaped) consumed by the release flow and quarterly delivery metrics.

No vulnerability reports have been received or resolved in the last 12 months (the project is only a few months old); SECURITY.md's "Hall of Fame" section explicitly reads "(none yet - be the first.)". SECURITY.md commits to crediting reporters in release notes and the Hall of Fame unless anonymity is requested (https://github.com/NaanyaBiz/haggle/blob/main/SECURITY.md). The one CVE fix in CHANGELOG (idna, dev-only lockfile) came via automated Dependabot monitoring, not an external report to this project.

https://github.com/NaanyaBiz/haggle/blob/main/SECURITY.md documents the full response process: private reporting via GitHub Private Security Advisories or security@naanya.biz, acknowledgement within 5 business days, graduated response targets by severity (critical 72 h / high 7 days / moderate-low 30 days), a self-escalation forcing function honest about the single-maintainer bound, a coordinated-disclosure window (14 days), and the known-vulnerable-release procedure (GHSA advisory, superseding release, HACS delisting).

CONTRIBUTING.md requires contributions to pass the documented dev loop - ruff check, ruff format, and strict mypy - before pushing (https://github.com/NaanyaBiz/haggle/blob/main/CONTRIBUTING.md). The specific style configuration is committed in pyproject.toml ([tool.ruff] with 17 rule families, line-length 88, isort ordering; [tool.mypy] strict = true) (https://github.com/NaanyaBiz/haggle/blob/main/pyproject.toml), and .github/workflows/ci.yml enforces ruff check, ruff format --check, and mypy as part of a required PR status check.

Coding style is enforced automatically by FLOSS tools: ruff lint, ruff format --check, and mypy run on every push and pull request in CI (https://github.com/NaanyaBiz/haggle/blob/main/.github/workflows/ci.yml, steps at lines 41-48), and the containing 'Test (Python 3.14)' job is one of eight required status checks under the zero-bypass protect-main ruleset, so a style violation blocks merge. The selected style is committed in pyproject.toml ([tool.ruff]) and also enforced locally via pre-commit hooks.

The project is a pure-Python Home Assistant custom integration: manifest.json declares "requirements": [] and the hatchling build backend produces no native binaries, so no compiler or linker is ever invoked and CC/CFLAGS-style variables have no referent.

The release build (https://github.com/NaanyaBiz/haggle/blob/main/.github/workflows/release.yml, "Build release artifact" step) zips the unmodified Python source of custom_components/haggle, excluding only pycache/.pyc; HACS installs that zip as-is. Nothing is stripped, minified, or compiled, so full source-level debugging information (readable source, tracebacks with line numbers) is always preserved in what users install.

The only build step is a single, flat packaging step in the release workflow: release.yml zips the contents of custom_components/haggle/ into haggle.zip in one command, then generates SBOMs and attestations from that artifact (https://github.com/NaanyaBiz/haggle/blob/main/.github/workflows/release.yml). There are no subdirectory builds, no Makefile recursion, and no cross-directory build dependencies; the integration is pure Python with zero compiled components.

Not applicable: haggle is a pure-Python Home Assistant custom integration whose source is used directly - HACS extracts the release archive and Home Assistant imports the .py files unchanged, so there is no compilation or build step to reproduce bit-for-bit. The criterion explicitly permits N/A where source is used directly rather than compiled.

The integration is distributed via HACS (the Home Assistant community package manager) and is in the HACS default store; README section Install documents the install (HACS -> search Haggle -> Download -> restart) and section Removing documents uninstall via HA's Settings -> Devices & Services, including a best-effort revocation of the stored OAuth grant on removal (https://github.com/NaanyaBiz/haggle/blob/main/README.md). hacs.json configures the attested zip_release asset that HACS installs.

The installation system is HACS, which installs the integration into Home Assistant's standard custom_components/ location inside the user-chosen HA configuration directory - the platform's standard convention for install location (install and rollback steps documented at https://github.com/NaanyaBiz/haggle/blob/main/README.md#install). Nothing is compiled, so no DESTDIR-style build-time relocation applies to this artifact type; the install location follows the ecosystem convention exactly.

CONTRIBUTING.md section Dev loop (https://github.com/NaanyaBiz/haggle/blob/main/CONTRIBUTING.md) documents a one-command setup - uv sync installs the complete dev and test environment from the hash-pinned uv.lock - followed by uv run pytest / ruff / mypy / pre-commit, matching what CI runs. A committed .devcontainer/devcontainer.json additionally provides a ready-made containerized dev environment with uv preinstalled.

Runtime dependencies are declared machine-readably in https://github.com/NaanyaBiz/haggle/blob/main/custom_components/haggle/manifest.json ("requirements": [] - the integration deliberately ships zero packages; everything it imports is vendored and pinned by Home Assistant core, as documented in SECURITY.md's supply-chain section). Development/test dependencies are declared in https://github.com/NaanyaBiz/haggle/blob/main/pyproject.toml and hash-pinned in uv.lock; Dependabot processes both the pip and github-actions ecosystems weekly.

Dependabot runs weekly on both the pip lockfile and github-actions ecosystems (https://github.com/NaanyaBiz/haggle/blob/main/.github/dependabot.yml), and every PR is gated by a required "Dependency review" check (actions/dependency-review-action, fail-on-severity: moderate, vulnerability-check: true) in ci.yml. SECURITY.md documents the triage ladder for alerts (critical 72 h / high 7 d / rest 30 d) and the exploitability analysis: manifest.json ships zero runtime requirements, so lockfile CVEs are dev/CI-only and are triaged on that recorded basis.

The shipped integration reuses only components vendored and version-pinned by Home Assistant core - https://github.com/NaanyaBiz/haggle/blob/main/custom_components/haggle/manifest.json declares "requirements": [] - so users receive standard platform-provided components. Development dependencies are enumerated in pyproject.toml and hash-locked per artifact in uv.lock, and https://github.com/NaanyaBiz/haggle/blob/main/.github/dependabot.yml runs weekly grouped update PRs for both the pip and github-actions ecosystems.

Ruff's pyupgrade (UP), flake8-async (ASYNC), and bugbear (B) rule families are enabled in pyproject.toml and gate every PR, flagging obsolete Python idioms and deprecated patterns (https://github.com/NaanyaBiz/haggle/blob/main/pyproject.toml); pytest runs with filterwarnings = "error" so deprecation warnings from the project's own code fail the suite (upstream homeassistant DeprecationWarnings are the only scoped exception). A weekly compat workflow additionally runs the full suite against the latest Home Assistant releases including betas to catch upcoming upstream deprecations early (https://github.com/NaanyaBiz/haggle/blob/main/.github/workflows/compat.yml).

The full automated test suite (pytest, with a combined line+branch coverage floor of 89% enforced via --cov-fail-under) runs on every push to main and every pull request via https://github.com/NaanyaBiz/haggle/blob/main/.github/workflows/ci.yml, producing a success/failure report as a GitHub check run on each commit; the check is required for merge by the protect-main ruleset.

The committed test strategy (https://github.com/NaanyaBiz/haggle/blob/main/docs/testing.md) requires that every escaped defect gets a named, pinned regression test and lists the existing pins (e.g. test_uses_outer_consumption_quantity_not_inner_values, test_baseline_looked_up_at_earliest_fetched_hour, test_band_reachback_baseline_after_long_absence). Verified in git history: 14 of the 16 integration-code bug-fix commits in the last six months (~87%) included automated-test additions or changes in the same commit, well above the 50% threshold.

The FLOSS test suite (pytest + coverage.py, ~254 tests including recorder-backed integration tests) is gated in CI at a combined line+branch coverage floor of 89% via --cov-fail-under=89 in https://github.com/NaanyaBiz/haggle/blob/main/.github/workflows/ci.yml, part of the required "Test (Python 3.14)" status check enforced by the zero-bypass protect-main ruleset. Current statement (line) coverage is 91.6% (local coverage.xml line-rate 0.9162; https://github.com/NaanyaBiz/haggle/blob/main/docs/testing.md records 90.0% combined at floor-setting time and defines the floor as an upward-only ratchet).

docs/testing.md (https://github.com/NaanyaBiz/haggle/blob/main/docs/testing.md) is the formal written test policy: its "Required depth per change type" section mandates automated tests for every functional change class (new endpoint => new fixture + parser tests; coordinator/statistics change => harness-integration tests, with real-recorder tests for sum-chain changes; every escaped defect => a named pinned regression test), enforced by the required CI check with a ratcheting coverage floor (--cov-fail-under=89). CONTRIBUTING.md and AGENTS.md's "Adding a New Endpoint" procedure repeat the tests-required rule for contributors.

https://github.com/NaanyaBiz/haggle/blob/main/CONTRIBUTING.md requires new-endpoint contributions to "Add an anonymised fixture, parser, client method, and tests", and https://github.com/NaanyaBiz/haggle/blob/main/docs/testing.md section "Required depth per change type" mandates the specific test layer for every class of change (new endpoint => new fixture + parser tests; cumulative-sum changes => recorder-backed tests in test_recorder_statistics.py; escaped defects => a named pinned regression test), enforced by CI's ratcheting 89% coverage floor.

Warnings are maximally strict and enforced in CI: mypy runs with strict = true plus warn_unreachable, warn_unused_ignores, and warn_redundant_casts; ruff enables 17 rule families including security (flake8-bandit), pylint, bugbear, and a max-complexity 12 gate; and pytest converts warnings to errors (filterwarnings = "error" with narrowly scoped upstream exceptions) - all configured in pyproject.toml (https://github.com/NaanyaBiz/haggle/blob/main/pyproject.toml) and run as part of the required "Test (Python 3.14)" PR check in .github/workflows/ci.yml.

Secure design principles are applied and documented per trust boundary in the committed threat model (https://github.com/NaanyaBiz/haggle/blob/main/docs/threat-model.md section 3): all untrusted AGL JSON passes allowlist parsing with numeric clamping to finite non-negative values (complete mediation / input validation, fuzz-enforced); least privilege governs OAuth scopes (read-only, with a documented re-assessment tripwire on any write scope) and CI tokens (read-only default, job-scoped writes); fail-safe defaults appear as fail-closed release gates (tag ancestry + signature verification) and a fail-closed secret-scanner self-test; secret exposure is minimised (memory-only 15-minute access token, rotate-on-use refresh token, hash-only fallback unique_id).