Ratchet the keg catalog floor to 115 to match the shipped 0.3.3
catalog. Archive the change that added Anheuser-Busch Bud (48050).
Co-authored-by: Cursor <cursoragent@cursor.com>
The DE/AT wrap is a distinct SKU from the UK Budweiser keg at 31747.
Observed from a fitted machine in issue #3. Bump to 0.3.3.
Co-authored-by: Cursor <cursoragent@cursor.com>
Adds two sections:
- Git Credential Helper: the project-scope carve-out permitting
'store --file=.git/credentials', with the idempotent start-of-session
check to run unprompted when that file exists.
- Project and Session Hygiene: points at PROJECT_HYGIENE.md and the
convention of maintaining it outside the worktree.
Also clarifies that the integration branch is e.g. master in the branch
boundary note and in archive step 2.
The working copy of this file had additionally dropped the 'Sync delta
specs' close-out step (added in 70928ba) and the Tech Stack section.
Both are restored here — the deletions were unrelated to the sections
being added and appear to have come from editing a stale copy.
Co-authored-by: Cursor <cursoragent@cursor.com>
Syncs the delta into openspec/specs/entities/spec.md, retrofitting the
Keg name sensor and Keg product ID sensor requirements that PR #2 shipped
without ever updating the spec, and adding both to the entity-name
translations scenario.
Note that openspec validate --specs still fails on all five spec files
for a missing "## Purpose" section. That is pre-existing and repo-wide,
not caused by this sync — verified by stashing the change and re-running.
Left alone rather than fixed across five files here.
PROJECT_HYGIENE learnings, three of them found while doing this work:
- Never add a non-numeric key to keg_catalog.json. The loader's
{int(k): v ...} raises on it and the except clause returns an empty
dict, so the whole catalog dies silently at debug level. This is a
trap precisely because embedding provenance in that file is the
obvious next idea.
- test_harness.py is stale: it reads a user_id key that
.credentials.json no longer has, so it exits immediately.
- All five openspec/specs files already fail validation, so a failing
spec validation does not imply you broke something.
Group 5 (on-device) is recorded as verification debt rather than marked
done. The catalog was replaced wholesale and verified statically only;
the live resolve path is unexercised because no HA is reachable from the
dev host and the harness refresh token has expired. v0.3.2 exists so
that check can happen through HACS.
Implementation is on agent/backport-keg-catalog. Groups 1-4 and 6.1-6.3
are done; group 5 (on-device) is blocked on the repo owner and the reason
is recorded in tasks.md.
Two artifact corrections that came out of the apply phase:
design.md now cherry-picks Brett's commit instead of copying the file.
The original decision rejected a cherry-pick on the assumption that the
pre-v0.1 merge-base would make it conflict. Wrong: 0982d20 touches one
file, and that file at 0982d20^ is byte-identical to master's, so only
the touched blob has to match and it applies clean. This is the better
option anyway — copying would have landed 28 observed keg names under the
committer's name with the author erased, whereas the cherry-pick keeps
Brett as author and carries the commit message that documents the
provenance and each of the four corrections.
design.md also records a trap found while writing the tests, because it
invalidates the provenance-marker idea the risks section suggested:
_load_keg_catalog builds {int(k): v ...} and catches ValueError by
returning {}, so adding a "_meta" or "_source" key to the catalog would
disable it entirely and leave every keg with no name, logged only at
debug level. Embedding metadata requires changing the loader first.
Companion to the previous commit, which is Brett Jenkins' catalog work
cherry-picked with authorship intact rather than copied in as data. This
commit adds what the backport needs around it.
README: credit Brett and his fork for the keg name sensor, the Keg and
Keg Product sensors, and the whole 114-entry catalog, and explain why the
catalog is hand-maintained — the API will not return the ID-to-name
mapping in bulk, so every entry is observed from a machine with that keg
fitted and none of it can be inferred. Also tells a user with a blank Keg
sensor to report their Keg Product ID, which is the only way the catalog
grows.
tests/test_keg_catalog.py: format and content guards for the spec
scenarios, stdlib-only so it runs under python3 -m unittest alongside
test_keg_detection.py without the opt-in HA harness.
Two of those guards cover failure modes that are silent rather than loud:
- Duplicate keys. json.loads() keeps the last one, so a repeated ID
would quietly discard an observed name. Only a pair-count comparison
sees it.
- Non-numeric keys. _load_keg_catalog builds {int(k): v ...} and
catches ValueError by returning an empty dict, so one "_meta" or
"_source" key would disable the entire catalog and leave every keg
with no name. This matters because embedding attribution or
provenance in the JSON is the obvious next idea, and it cannot be
done without changing the loader first. The test documents that.
Version 0.3.2, continuing from 0.3.1. Not the fork's 0.4.1: 0f3b4c2
renumbered to 0.3.1 deliberately because no v0.4.0 tag was ever cut.
hacs.json is left alone, including the 2024.11.0 floor the fork predates.
Temperature sensor requirement now mandates rejecting out-of-range
firmware sentinels and reporting no value, with scenarios covering the
-128 case, the fallback chain, and non-numeric input.
Co-authored-by: Cursor <cursoragent@cursor.com>
Filters firmware sentinel values (notably -128, 0x80 as signed int8)
from the temperature sensor so they no longer pollute Home Assistant
history and long-term statistics.
ClosesFalkvinge/hassio-integration-perfectdraft-pro#4
This is the full mapping — every keg the PerfectDraft app can select, including ones no
longer sold but which can still be sat in a machine. The same mapping drives the
seemy.beer tap sign, where it has been running well.
The ids can't be looked up in bulk, so each one was observed directly from the machine.
Every entry here is measured rather than inferred.
28 kegs previously showed no name at all in Home Assistant. Now named, among them
Kopparberg Crisp Apple, Leffe Prestige, Kwak Rouge, Hertog Jan Grand Pilsener and all
three Diekirchs.
Four existing names were wrong rather than merely styled differently:
32814 Birra Del Borgo Lisa -> Romola the beer was renamed, so this was
showing one that no longer exists
44331 Short Date Ninkasi Flower Lager 6L Keg BBE June 2024 -> Ninkasi Flower Lager
44536 Short Date Tiny Rebel Stay Puft 6L Keg BBE August 2024 -> Tiny Rebel Stay Puft
shop listings still carrying a
best-before date from 2024
43235 Corona Cero (0.0% abv) 6L Keg -> Corona Cero (0.0% abv) 6L is the pack
Eleven other names differ only in styling (Trooper vs TROOPER, St vs Saint Feuillien).
Left alone deliberately: this is a display name, the existing spellings are the ones the
shop uses, and rewriting them would only make the diff harder to read.
File formatting is untouched (no indent, numeric key order), so the diff is just the
real additions.
(cherry picked from commit 0982d20737d22c241c736fe657b3e0d02625b50c)
Backported-from: https://github.com/brettjenkins/hassio-integration-perfectdraft-pro
Backported-via: brettjenkins/hassio-integration-perfectdraft-pro#1
Implementation complete on agent/temperature-sentinel (133f708).
Sections 1-3 done, 4.1 and 4.3 done; 4.2 and 4.4 are public-repo
actions held for maintainer go-ahead.
Co-authored-by: Cursor <cursoragent@cursor.com>
An uninitialised probe reports -128 (0x80 read as a signed 8-bit
integer) while the refrigeration starts up. The cloud API relays it
verbatim and the sensor reported it as a real measurement, polluting
history graphs and long-term statistics.
Readings outside -20..50 C are now treated as firmware sentinels and
the sensor reports no value, so the state is 'unknown' and the recorder
excludes it. A range check is used rather than matching -128 exactly so
sibling sentinels are caught too. Both temperature fields are validated;
previously the details.temperature fallback was used unconditionally.
The sensor deliberately reports 'unknown' rather than going unavailable:
the coordinator poll succeeded and only the reading is missing, which
matches how every other sensor here signals absent data.
Logic lives in a new HA-free temperature.py so it can be unit-tested
without the Home Assistant harness, following the keg_detection.py
precedent.
Refs: Falkvinge/hassio-integration-perfectdraft-pro#4
Co-authored-by: Cursor <cursoragent@cursor.com>
Sentinel temperature readings (-128, i.e. 0x80 as signed int8) from an
uninitialised probe are reported as real measurements and pollute
recorder statistics. Proposal, design, entities delta spec and tasks
for filtering them by plausible range.
Refs: Falkvinge/hassio-integration-perfectdraft-pro#4
Co-authored-by: Cursor <cursoragent@cursor.com>
Investigation of @brettjenkins' fork found exactly one substantive
difference from master in custom_components/: the keg name catalog, 86
entries against the fork's 114. keg_detection.py, sensor.py,
coordinator.py, api.py and const.py are byte-identical, and the
config_flow.py and translation differences are the fork lacking our
September reauth work. GitHub's "38 ahead / 46 behind" is an artifact of
the mirror's rewritten history — the merge-base predates v0.1.
The 28 missing IDs are kegs the PerfectDraft app can select, so they
render as a blank Keg sensor today. Four names we do ship are wrong
rather than merely styled differently, including one beer that no longer
exists under that name.
The change also retrofits the entities requirements for the Keg and Keg
Product sensors, which PR #2 shipped without touching
openspec/specs/entities/spec.md. That gap has to close here because the
catalog requirement has nothing to attach to otherwise.
Explicitly out of scope: the fork's hacs.json without the 2024.11.0
floor (that floor is ours, added by 0f3b4c2), the fork's 0.4.1 version
(0f3b4c2 renumbered to 0.3.1 deliberately), and changing what an
unmapped ID reports.
Co-authored-by: Cursor <cursoragent@cursor.com>
Archived to openspec/changes/archive/2026-09-06-fix-reauth-flow.
Reauth confirmed working on the live machine running v0.3.1; three
non-blocking on-device checks archived unverified with reasons
recorded, and the keg-dependent one carried forward in
PROJECT_HYGIENE.md.
Co-authored-by: Cursor <cursoragent@cursor.com>
Reauth itself confirmed live on v0.3.1. Tasks 6.6, 6.7 and 8.8 archived
unverified: no keg was fitted, so there was no freshness baseline to
check, and the other two are cosmetic dialog-rendering checks already
covered by tests. The keg-dependent check is carried into
PROJECT_HYGIENE.md as verification debt for the next keg change.
Co-authored-by: Cursor <cursoragent@cursor.com>
Live instance running the v0.3.1 release build: the reauth repair
appeared and the flow completed on "Re-authentication successful"
rather than the "already configured" dead-end. Tasks 6.4 and 6.5 done;
6.6 (polling/history/freshness baseline), 6.7 and 8.8 still open.
Co-authored-by: Cursor <cursoragent@cursor.com>
Records section 8 (the already_in_progress finding and its fix) and
renames the translation requirement to cover every abort reason, with
scenarios for the concurrent-flow path and source-derived enumeration.
Co-authored-by: Cursor <cursoragent@cursor.com>
Verification caught this change violating its own requirement that every
abort reason the flow can emit has a translation. async_set_unique_id()
defaults to raise_on_progress=True and raises already_in_progress when
another flow holds the same unique ID. That is reachable, and reachable
by exactly the users this change is for: park a reauth flow, give up,
try Add Integration for the same account, and the raw key surfaces.
The coverage test was hardcoded to three reasons, so it checked a "for
every" requirement against a list written by hand and passed anyway.
Replace it with an AST scan of config_flow.py that resolves each
aborting helper call to the reason it raises, honouring explicit reason=
and the raise_on_progress=False opt-out, plus a sanity test so a scanner
that goes blind fails instead of silently passing. Confirmed the new
check fails against the pre-fix translation files.
Also adds a regression test for the concurrent-flow path, which is the
evidence that this abort is real rather than theoretical.
Co-authored-by: Cursor <cursoragent@cursor.com>
Marks sections 1-5 and the automated verification in 6 done, syncs the
config-flow delta into the main specs, and records the deferred
Cognito-token-persistence item in PROJECT_HYGIENE.md.
Archive (7.5/7.6) is deliberately held until on-device verification
(6.4-6.7) confirms the fix against the live machine.
Co-authored-by: Cursor <cursoragent@cursor.com>
async_step_token is shared by the user and reauth sources but was written
only for the former. It called _abort_if_unique_id_configured() on every
path, and during reauth the unique ID belongs to the entry being repaired,
so the duplicate guard fired by design: authentication succeeded, the flow
aborted with already_configured, the new tokens were discarded, and the
coordinator's next poll re-raised the reauth repair. The integration was
unrecoverable through the UI short of delete-and-re-add, which costs entity
history and the restored keg-freshness baseline.
Branch on self.source at the terminal step, per HA's documented pattern for
flows shared between setup and reauth: reauth now guards with
_abort_if_unique_id_mismatch() and persists through
async_update_reload_and_abort(), which merges the new tokens into the
existing entry, keeps email and machine ID, reloads, and aborts with
reauth_successful. The user path keeps _abort_if_unique_id_configured()
unchanged.
Reauth also stops re-fetching /api/me when the entry already records a
machine ID, removing a round trip from a flow the user waits on and a
failure mode where a transient /api/me error turned a successful sign-in
into cannot_connect.
The helpers require core 2024.11, so declare that floor in hacs.json —
otherwise older cores would AttributeError mid-flow, which is worse than
the bug being fixed.
Adds the repo's first HA test harness (requirements-test.txt, opt-in) with
regression tests covering token persistence, entry reload, account
mismatch, case-insensitive email, and the explicit assertion that reauth
never aborts as already_configured. tests/test_keg_detection.py still runs
standalone under python3 -m unittest.
Version set to 0.3.1 rather than the 0.4.0 that PR #2 introduced; no
v0.4.0 tag was ever cut, so nothing was released under that number.
Co-authored-by: Cursor <cursoragent@cursor.com>
Reauth aborts with already_configured because async_step_token calls
_abort_if_unique_id_configured() on every source, including reauth where
a matching unique ID is the expected condition. Fresh tokens are discarded
and the entry stays broken.
Artifacts cover the source-aware fix, the 2024.11 core floor the reauth
helpers require, and the pytest-homeassistant-custom-component harness
needed to regression-test a config flow.
Co-authored-by: Cursor <cursoragent@cursor.com>
Resolves the tapped keg's product id to a beer name via a bundled
catalog (keg_catalog.json), exposing it as a new Keg sensor alongside
the existing Keg Remaining/Freshness sensors.
Corroborating observation: on a power cycle / integration reload, Keg
Remaining did not change while pours reset to 0. Confirms volume-jump
detection (b/c) and the manual button are power-cycle-safe.
Co-authored-by: Cursor <cursoragent@cursor.com>
Empirically confirmed numberOfPoursSinceStartup resets to 0 on a machine
power cycle, so it cannot reliably signal a keg change. Logs the finding
and a TODO to remove the pour-count-based detection (trigger a + last_pours
tracking) in a future OpenSpec change; volume jumps + the manual button
already cover keg changes and are power-cycle-safe.
Co-authored-by: Cursor <cursoragent@cursor.com>
Task 5.3 confirmed on-device (Mark Keg Changed button and volume-jump
detection both work). Applied the entities delta to the main spec: the
keg freshness sensor now documents the volume-jump triggers and
last_volume restore, plus the new Manual keg-change button requirement.
Co-authored-by: Cursor <cursoragent@cursor.com>
Keg-change detection previously fired only when the pour counter reset
to 0 while the keg read near full. That misses the common case where the
user swaps the keg and pours immediately, so pours never reads 0.
Detection now also fires on two volume-based signals (independent of the
pour counter): (b) remaining volume jumping from below 80% to at least
95%, and (c) any upward jump of at least 50 percentage points. The
decision logic is extracted to a dependency-free keg_detection module
with unit tests covering each trigger and the swap-then-pour case.
Adds a "Mark Keg Changed" button as a deterministic manual override,
wired to the freshness sensor via a dispatcher signal; the sensor now
tracks and restores last_volume alongside last_pours.
Bumps version to 0.3.0.
Co-authored-by: Cursor <cursoragent@cursor.com>
Copied from sibling Hassio projects and referenced by AGENTS.md's
standard flow. The script is generic (relative .worktree paths, master
base, agent/<topic> branches), so no path or project-name changes were
needed.
Co-authored-by: Cursor <cursoragent@cursor.com>
Propose smarter keg-change detection plus a manual override.
Detection gains two volume-based triggers (refill to near-full;
>=50-point upward jump) so a swap is caught even when pours never
resets to 0 (the swap-then-immediate-pour case). Adds a "Mark Keg
Changed" button as a deterministic fallback.
Co-authored-by: Cursor <cursoragent@cursor.com>
Critical fix:
- Cognito refresh now parses response with content_type=None
(was crashing after 1hr when access token expired)
HACS compliance:
- Added README.md with full setup instructions including the
token generation command
- Fixed manifest.json URLs to point at actual repo
- Version bumped to 0.2.0
Brand:
- Added brand/icon.png (PerfectDraft glass icon from official app)
New sensor:
- Keg Freshness: 30-day countdown from keg insertion, detected
via numberOfPoursSinceStartup reset + kegVolume near full,
persisted across restarts via RestoreEntity
Polish:
- Fixed MALFORMED_ARGUMENT in token step description
- Cleaner description referencing README for instructions
Made-with: Cursor