2 Commits
Author SHA1 Message Date
rickandCursor 8e02215f01 openspec: add Purpose sections to all five main specs
OpenSpec 1.16 requires ## Purpose; the specs predate that. Purposes are reconstructed from the 2026-04-13 greenfield proposal and the current requirements. Plain validation now passes 5/5; strict still flags two over-long requirements, tracked in PROJECT_HYGIENE.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 12:11:15 +01:00
rickandCursor be00125465 openspec: archive add-french-translation, sync hacs-packaging spec
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 18:43:34 +01:00
11 changed files with 33 additions and 3 deletions
+2 -2
View File
@@ -196,10 +196,10 @@ When the user corrects your approach, append a one-line rule here before ending
- **A new integration catalog ID is not done until the card maps it.** The companion card joins on `kegId` against `scripts/keg-catalog.reference.json`. Adding a row to `keg_catalog.json` without binding the card entry (and re-syncing that snapshot) ships a named **Keg** sensor that the card still treats as unknown. The card may already have the beer under a slug with no `kegId` — check before adding a duplicate entry.
- **TODO — verification debt from `backport-keg-catalog` (archived 2026-09-06), clear this after installing v0.3.2 via HACS: confirm the `Keg` sensor still resolves the fitted keg.** The catalog file was replaced wholesale (86 → 114 entries) and verified statically only: exact diff shape, 114 int keys through the loader, and format guards in `tests/test_keg_catalog.py`. What was never exercised is the live path. On-device checks were impossible at the time — no HA on the dev host, and `.credentials.json`'s refresh token had expired (`NotAuthorizedException: Refresh Token has expired`), so even `test_harness.py` could not reach the API. Task group 5 in the archived change lists the four checks.
- **`test_harness.py` is stale: it reads `user_id` from `.credentials.json`, which now holds `email` / `access_token` / `id_token` / `refresh_token`.** It exits before doing anything useful. Fix the key names (and refresh the token per the README's reCAPTCHA step) before relying on it.
- **All five files in `openspec/specs/` fail `openspec validate --specs`** for a missing `## Purpose` section. Pre-existing and repo-wide as of 2026-09-06, so a failing spec validation is not necessarily caused by your change — check whether the error is only the Purpose one before chasing it.
- **TODO — verification debt from `fix-cognito-signin` (v0.4.4 shipped without on-device checks, maintainer decision 2026-11-07).** The Cognito direct sign-in was verified only by the automated suite (stdlib API tests and pytest config-flow tests) and the README token was checked in Firefox and Chromium; no sign-in reached the live service from Home Assistant. When there is time for a reinstall: (1) add the integration from scratch with a README token and confirm sensors populate; (2) a wrong password must return to the email/password form with `invalid_credentials` and Cognito's reason, and a token older than 2 minutes must stay on the token step with `token_rejected`; (3) trigger a reauth and confirm it succeeds (with a keg fitted, this also clears the Keg Freshness TODO above). Details in the archived change's `tasks.md`, section "Deferred".
- **TODO — verification debt from `add-keg-48180` and `add-oktoberfest-keg-art` (card 0.4.4 and 0.4.5 shipped without on-device checks, maintainer decisions 2026-11-07).** Do it together with the `fix-cognito-signin` checks above, on integration and card 0.4.5 or later: confirm the card editor's beer picker shows artwork for Camden Stout, Löwenbräu Oktoberfestbier and Spaten Oktoberfestbier, and that the two Oktoberfest images are sharp in the `hero` layout. With a 48180 keg fitted, confirm the Keg sensor reads "Camden Stout" and the card brands it. With a 29745 keg fitted, the sensor must read "Löwenbräu Oktoberfestbier" (with umlauts).
- **TODO — main specs fail `openspec validate --specs --strict` (all 5, pre-existing; seen 2026-11-07).** None of `openspec/specs/*/spec.md` has the `## Purpose` / `## Requirements` headers the current CLI requires; requirements start directly at `### Requirement:`. Archiving still works, but sync tooling and validation expect the headers. Fix in one housekeeping commit: add a short `## Purpose` and a `## Requirements` heading to each spec, then re-run strict validation.
- **Every main spec needs `## Purpose` above `## Requirements`** (OpenSpec 1.16 rejects specs without it; all five were back-filled 2026-11-08). A new capability gets its Purpose from the delta's `## Purpose` at archive; check `openspec validate --specs` passes after every sync.
- **TODO — two main specs still fail `openspec validate --specs --strict`** on requirement text over 500 characters (a warning, so plain validation passes): `api-client` "Sign-in with reCAPTCHA token" and `entities` "Keg name sensor". Split each into single-behavior requirements in a change made for that purpose, keeping every scenario; do not trim them inside an unrelated change.
- **TODO — own OpenSpec change: persist Cognito-refreshed tokens back to the config entry.** `PerfectDraftApiClient.refresh_access_token()` updates `_access_token`/`_id_token` in memory only, so every HA restart reloads the stale access token and burns a wasted 401-plus-refresh round trip before the first successful poll. Harmless today because the refresh token is what actually gates reauth and Cognito's `REFRESH_TOKEN_AUTH` never issues a new one, so nothing is lost — just wasteful. Deferred out of `fix-reauth-flow` to keep that diff surgical.
- **TODO — housekeeping, after `fix-cognito-signin` / `add-keg-48180` ship: take the GitHub token out of the `github` remote URLs** in both this repo and `Hassio-PerfectDraftPro-Component`. Not a leak (never committed; `.git/` is untracked), but `git remote -v` prints it. Order matters: first change `credential.helper` to an **absolute** path (`store --file=/home/rick/Lab/Dev/<repo>/.git/credentials`) — the current relative `.git/credentials` resolves against the worktree root, where `.git` is a file, so pushes from `.worktree/<topic>` only reach `github` (whose URL carries the token); pushing to `origin` from a worktree fails with "unable to open .git/credentials: Not a directory". Until fixed, push agent branches from the main checkout: `git push origin agent/<topic>` (no branch switch needed). Then strip the URL, run `git ls-remote github` from a worktree to prove auth, and update the `AGENTS.md` helper command to the absolute form.
- **Config-flow tests run in `.venv-test` (main checkout) on the system Python 3.14** with `pytest-homeassistant-custom-component==0.13.375` (core 2026.10.4). Run them from a worktree as `../../.venv-test/bin/pytest tests/`. Do not pin a harness that needs Python 3.12: there is no 3.12 and no C compiler on the dev host, so old numpy cannot build.
+4
View File
@@ -1,3 +1,7 @@
## Purpose
The async client for PerfectDraft's cloud services and the integration's only point of contact with them. It signs in through AWS Cognito with the account's email, password and a reCAPTCHA verification token, refreshes the session without user involvement, and fetches the account's machines and their telemetry from `api.perfectdraft.com`.
## Requirements
### Requirement: Async HTTP client
+4
View File
@@ -1,3 +1,7 @@
## Purpose
The Home Assistant UI flows that connect a PerfectDraft account: initial setup with email, password and a browser-generated verification token; reauthentication when the session can no longer be refreshed; and an options form for the polling interval. Failures tell the user which input was rejected and why.
## Requirements
### Requirement: User step collects email and password
+4
View File
@@ -1,3 +1,7 @@
## Purpose
Polls the PerfectDraft API once per interval for each configured account and shares the result with every entity, so request volume stays low enough to avoid the API's rate limiting. It also turns API failures into Home Assistant's reauth and unavailable states.
## Requirements
### Requirement: Single DataUpdateCoordinator per config entry
+4
View File
@@ -1,3 +1,7 @@
## Purpose
The Home Assistant device and entities that represent a PerfectDraft machine on dashboards and in automations: beer temperature, keg level, the fitted keg and its beer name, machine status, pour data, and a client-side keg freshness countdown with a manual keg-change button.
## Requirements
### Requirement: HA Device per PerfectDraft machine
+15 -1
View File
@@ -1,3 +1,7 @@
## Purpose
The repository layout, metadata, branding, documentation and UI strings that let the integration be installed and updated through HACS and presented properly in Home Assistant, in English and French.
## Requirements
### Requirement: HACS-compliant repository structure
@@ -51,9 +55,19 @@ The repository SHALL be mirrored to GitHub for HACS compatibility, since HACS re
- **THEN** they SHALL be pushed to both the primary Gitea repo (origin) and the GitHub mirror (github)
### Requirement: Translations
The integration SHALL provide English UI strings for all config flow steps, errors, abort reasons, options, and entity names.
The integration SHALL provide English and French UI strings for all config flow steps, errors, abort reasons, options, and entity names. Every shipped translation file SHALL have exactly the same key structure as `strings.json`.
#### Scenario: Translation files
- **WHEN** HA renders the integration UI
- **THEN** `strings.json` and `translations/en.json` SHALL provide labels for all steps, fields, errors, and entity names
- **THEN** descriptions SHALL not contain curly braces (parsed as translation placeholders) or newlines (cause MALFORMED_ARGUMENT)
#### Scenario: French UI
- **WHEN** HA renders the integration UI with its language set to French
- **THEN** `translations/fr.json` SHALL provide French labels for all steps, fields, errors, abort reasons, options, and entity names
- **THEN** each French string SHALL use the same `{placeholder}` names as its English counterpart
#### Scenario: Key parity
- **WHEN** a key is added to, renamed in, or removed from `strings.json`
- **THEN** `translations/en.json` and `translations/fr.json` SHALL be updated to the same key structure in the same change
- **THEN** the test suite SHALL fail if any of the three files has a key the others lack