diff --git a/PROJECT_HYGIENE.md b/PROJECT_HYGIENE.md index a8c8f55..a06919e 100644 --- a/PROJECT_HYGIENE.md +++ b/PROJECT_HYGIENE.md @@ -196,13 +196,14 @@ When the user corrects your approach, append a one-line rule here before ending - **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.3.5 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` (card 0.4.3 shipped without an on-device check, maintainer decision 2026-11-07).** Do it together with the `fix-cognito-signin` checks above: on a dashboard with card 0.4.3, confirm the card editor's beer picker lists Camden Stout with its artwork; with a 48180 keg fitted, confirm the Keg sensor reads "Camden Stout" and the card brands 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` (card 0.4.4 shipped without an on-device check, maintainer decision 2026-11-07).** Do it together with the `fix-cognito-signin` checks above: on a dashboard with card 0.4.4, confirm the card editor's beer picker lists Camden Stout with its artwork; with a 48180 keg fitted, confirm the Keg sensor reads "Camden Stout" and the card brands it. - **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//.git/credentials`) — the current relative `.git/credentials` resolves against the worktree root, where `.git` is a file, so pushes from `.worktree/` 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/` (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. - **DevTools `copy()` cannot copy an async result in any browser.** Chromium removes `copy` once the typed command returns (`undefined` in `.then`/after `await`); Firefox's `copy()` only sets a `helperResult` read when evaluation returns, so a later call silently copies nothing — and a captured `copy` reference "works" in Chromium tests while failing in Firefox. Do not use `prompt(msg, value)` either: Chromium cuts the default value off at 2,000 chars, and reCAPTCHA tokens are ~2,450–2,700. For user-facing snippets, keep one command that adds a page button whose click calls `navigator.clipboard.writeText(value)`. Test console snippets in Firefox too, not only via CDP/Chromium. - **Cursor's embedded browser replaces `alert`/`confirm`/`prompt` with logging stubs** (`[CursorBrowser] Dialog suppressed`, history in `window.__cursorDialogConfig.dialogHistory`). A missing dialog there says nothing about real browsers; read the history to check the arguments, and have a human check the native dialog. +- **Version numbering (since 0.4.4, 2026-11-07): integration and card share major.minor; patch may diverge.** A fix to one package bumps only its patch (card 0.4.5 next to integration 0.4.4); a joint release brings both to the same number again. Never use letter suffixes (`0.4.4b`): HACS (PEP 440) and npm (SemVer) treat them as pre-releases that sort *before* 0.4.4, so HACS would not offer the update. - **`gh` is not installed; use the GitHub REST API with `curl`.** Get the token with `printf 'protocol=https\nhost=github.com\n\n' | git credential fill`. The token is fine-grained: since 2026-11-07 it has Issues and Pull requests read/write in addition to admin/push. A `403 Resource not accessible by personal access token` means a permission is missing on the token, not a bad token. - **TODO — own OpenSpec change + release: remove pour-count-based keg detection** from `PerfectDraftKegFreshnessSensor` in `sensor.py`: trigger (a) `pours == 0 && kegVolume > 5.5 && last_pours != 0`, plus the `_last_pours` field and its restore/exposure/rebaseline. It can false-fire on a power cycle while the keg is above ~92% full, and adds nothing the volume triggers (b/c) and the Mark Keg Changed button don't already cover. diff --git a/openspec/changes/add-keg-48180/design.md b/openspec/changes/add-keg-48180/design.md index 1df15f3..7019ad5 100644 --- a/openspec/changes/add-keg-48180/design.md +++ b/openspec/changes/add-keg-48180/design.md @@ -35,8 +35,8 @@ He has the keg fitted, which is the bar the catalog sets. The fork's "Nitro" may **Card entry: take PR #2's artwork and fields, and verify the ABV.** We use slug `camden-stout`, brewery "Camden Town Brewery", style "Stout", colours as in PR #2, `imagePath: kegImage("camden-stout")`, and `kegId: "48180"`. The ABV of 4.0 is checked against Camden's or PerfectDraft's product page before landing. The card displays it, and a stout at exactly the session-pale ABV is worth a second look. The artwork file comes from PR #2's head commit unchanged. `dist/` is rebuilt with our `npm run build`, not taken from the PR. -**Versions: no separate integration bump; card 0.4.3.** -`fix-cognito-signin` owns the integration's 0.3.5 bump. The card bumps 0.4.2 → 0.4.3 in `package.json`, `CARD_VERSION` and `EDITOR_VERSION`. PR #2's `package-lock.json` jump from 0.3.1 is a stale lockfile, so we regenerate the lockfile rather than copy it. +**Versions: both packages ship as 0.4.4; no separate integration bump here.** +On 2026-11-07 the maintainer synced the two version lines: the integration jumps 0.3.4 → 0.4.4 (owned by `fix-cognito-signin`) and the card 0.4.2 → 0.4.4. From here major.minor moves in lockstep and the patch number may diverge for a fix to only one package (for example card 0.4.5 alongside integration 0.4.4). Letter suffixes such as `0.4.4b` are not used: PEP 440 (HACS) and SemVer (npm) both read them as pre-releases that sort before 0.4.4. The card bumps in `package.json`, `CARD_VERSION` and `EDITOR_VERSION`. PR #2's `package-lock.json` jump from 0.3.1 is a stale lockfile, so we regenerate the lockfile rather than copy it. ## Risks / Trade-offs diff --git a/openspec/changes/add-keg-48180/proposal.md b/openspec/changes/add-keg-48180/proposal.md index a7c3268..c2cd030 100644 --- a/openspec/changes/add-keg-48180/proposal.md +++ b/openspec/changes/add-keg-48180/proposal.md @@ -4,7 +4,7 @@ Issue #9: product ID `48180` is missing from the bundled keg catalog, so the **K - PR #10 inserts `48180` between `48061` and `48134`, which fails `test_keys_in_ascending_numeric_order`. - PR #10 also re-pads the whole README sensor table for a one-number change. -- PR #10 bumps the integration to 0.3.5, a version owned by `fix-cognito-signin`, which ships in the same release. +- PR #10 bumps the integration to 0.3.5, which clashes with the version bump owned by `fix-cognito-signin`, which ships in the same release. - Card PR #2 pins its reference snapshot to PR #10's unmerged commit and ships a `dist/` built outside our toolchain. The name is also disputed. PR #10 says "Camden Stout", while brettjenkins' fork maps the same ID as "Camden Nitro Stout". @@ -13,11 +13,11 @@ The name is also disputed. PR #10 says "Camden Stout", while brettjenkins' fork - Add `48180` to `keg_catalog.json` as the last key, after `48134`. The name defaults to "Camden Stout", as reported by the person with the keg fitted. It changes to "Camden Nitro Stout" only if MThomas564 confirms the app or keg reads that way. - Ratchet the catalog floor from 116 to 117 in tests and the `entities` spec. Update the README count without reformatting the table. -- No integration version bump of its own. It ships in 0.3.5 with `fix-cognito-signin`. +- No integration version bump of its own. It ships in 0.4.4 with `fix-cognito-signin`. - Companion card: - Add a `camden-stout` entry with `kegId: "48180"` and the keg artwork from card PR #2. - Re-sync `scripts/keg-catalog.reference.json` to the integration commit that adds `48180`. - - Bump the card to 0.4.3 and rebuild `dist/`. + - Bump the card to 0.4.4 and rebuild `dist/`. - Credit MThomas564 as co-author on both commits, then close PR #10, card PR #2 and issue #9 with a pointer to the release. Not in scope: @@ -37,7 +37,7 @@ None. ## Impact -- Users with keg `48180` see its name on the **Keg** sensor after 0.3.5, and Camden Stout branding and artwork on the card after 0.4.3. +- Users with keg `48180` see its name on the **Keg** sensor after 0.4.4, and Camden Stout branding and artwork on the card after 0.4.4. - No entity churn, no migration, and no change for any other ID. - Integration: `keg_catalog.json`, `tests/test_keg_catalog.py`, `README.md`. - Card repo (`Hassio-PerfectDraftPro-Component`): `src/beer-catalog.ts`, `src/assets/kegs/camden-stout.webp`, `scripts/keg-catalog.reference.json`, `package.json`, `CARD_VERSION`, `EDITOR_VERSION`, `dist/`. diff --git a/openspec/changes/add-keg-48180/tasks.md b/openspec/changes/add-keg-48180/tasks.md index cab83dc..d5f016e 100644 --- a/openspec/changes/add-keg-48180/tasks.md +++ b/openspec/changes/add-keg-48180/tasks.md @@ -19,7 +19,7 @@ Work in `Hassio-PerfectDraftPro-Component`. - [x] 3.2 Add the `camden-stout` entry (name from 1.1, Camden Town Brewery, Stout, PR #2 colours, `imagePath: kegImage("camden-stout")`, `kegId: "48180"`) next to the other Camden rows; check the ABV against Camden's or PerfectDraft's product page and use that value - ABV 4.0% confirmed on Camden Town Brewery's "Camden X PerfectDraft Stout" listing (camdentownbrewery.com, 2026-11-07), which also calls the keg "Camden Stout" - [x] 3.3 Re-sync `scripts/keg-catalog.reference.json` from the integration commit in 2.4 and set `_upstreamCommit` to it -- [x] 3.4 Bump `package.json`, `CARD_VERSION` and `EDITOR_VERSION` to 0.4.3; regenerate `package-lock.json` with `npm install --package-lock-only` rather than copying PR #2's +- [x] 3.4 Bump `package.json`, `CARD_VERSION` and `EDITOR_VERSION` to 0.4.4; regenerate `package-lock.json` with `npm install --package-lock-only` rather than copying PR #2's - [x] 3.5 `npm run lint`, `npm run check:catalog` (117/117), `npm run build`; commit source and `dist/` with `Co-authored-by: MThomas564` ## 4. Joint verification @@ -27,13 +27,13 @@ Work in `Hassio-PerfectDraftPro-Component`. ## Deferred: shipping without on-device checks -Maintainer decision, 2026-11-07: ship card 0.4.3 and the 48180 catalog entry without this check (no time for a Home Assistant reinstall), as with `fix-cognito-signin` 5.2–5.4. Coverage at release: catalog unit tests (117 keys, ordering), `npm run lint`, `npm run check:catalog` (117/117) and a clean `npm run build` with the artwork in `dist/`. The open TODO is in `PROJECT_HYGIENE.md`. +Maintainer decision, 2026-11-07: ship card 0.4.4 and the 48180 catalog entry without this check (no time for a Home Assistant reinstall), as with `fix-cognito-signin` 5.2–5.4. Coverage at release: catalog unit tests (117 keys, ordering), `npm run lint`, `npm run check:catalog` (117/117) and a clean `npm run build` with the artwork in `dist/`. The open TODO is in `PROJECT_HYGIENE.md`. -- 4.1 With `fix-cognito-signin` also applied, install integration 0.3.5 and card 0.4.3 on Home Assistant; if a 48180 keg is unavailable, confirm instead that the card editor's beer picker lists the new entry with its artwork, and that `getBeerByKegId("48180")` resolves it in a browser console on the dashboard +- 4.1 With `fix-cognito-signin` also applied, install integration 0.4.4 and card 0.4.4 on Home Assistant; if a 48180 keg is unavailable, confirm instead that the card editor's beer picker lists the new entry with its artwork, and that `getBeerByKegId("48180")` resolves it in a browser console on the dashboard ## Workflow follow-up - Before archiving this change, archive `add-keg-47792` (complete since v0.3.4, never archived), so the `entities` main spec reads 116 before this delta lifts it to 117. -- Joint release: integration v0.3.5 (with `fix-cognito-signin`) and card v0.4.3, published together. The release notes thank MThomas564 and tell users to update both. +- Joint release: integration v0.4.4 (with `fix-cognito-signin`) and card v0.4.4, published together. The release notes thank MThomas564 and tell users to update both. - After the release, close PR #10, card PR #2 and issue #9, each with a thank-you, the commit links and the release link. - Archive per `AGENTS.md` in both repos (merge, push, sync the `entities` spec, archive, remove worktrees and branches). diff --git a/openspec/changes/fix-cognito-signin/design.md b/openspec/changes/fix-cognito-signin/design.md index f404041..f524336 100644 --- a/openspec/changes/fix-cognito-signin/design.md +++ b/openspec/changes/fix-cognito-signin/design.md @@ -58,7 +58,7 @@ Home Assistant fills error placeholders from `description_placeholders`. Every ` - **PerfectDraft changes the Lambda again.** The reason now reaches the UI, so the next break is diagnosable from a user's screenshot. Nothing else changes. - **PerfectDraft disables `USER_PASSWORD_AUTH` on the app client.** Cognito would return `InvalidParameterException`, which surfaces as `invalid_auth` with the reason. There is no mitigation beyond reacting. The shop itself appears to rely on this flow. -- **We cannot test against the real service before release.** The stored refresh token on the dev host has expired. The planned mitigation, a manual sign-in through Home Assistant before tagging (tasks 5.2–5.4), was waived by the maintainer on 2026-11-07: v0.3.5 ships with only the automated suite and the browser-verified README token. If live sign-in fails, the `{reason}` placeholder puts the error in front of the reporting user, and the checks are owed as a post-release TODO in `PROJECT_HYGIENE.md`. +- **We cannot test against the real service before release.** The stored refresh token on the dev host has expired. The planned mitigation, a manual sign-in through Home Assistant before tagging (tasks 5.2–5.4), was waived by the maintainer on 2026-11-07: v0.4.4 ships with only the automated suite and the browser-verified README token. If live sign-in fails, the `{reason}` placeholder puts the error in front of the reporting user, and the checks are owed as a post-release TODO in `PROJECT_HYGIENE.md`. - **The clipboard write fails in some browser.** The black box then shows "Copy failed: …", and the README tells the user to copy the token from the console, where the command also prints it. ## Migration Plan diff --git a/openspec/changes/fix-cognito-signin/proposal.md b/openspec/changes/fix-cognito-signin/proposal.md index 07dd46f..c2d5990 100644 --- a/openspec/changes/fix-cognito-signin/proposal.md +++ b/openspec/changes/fix-cognito-signin/proposal.md @@ -15,7 +15,7 @@ The config flow made this hard to diagnose. Every authentication failure shows t - Anything else stays on the token form with `invalid_auth`. - All three show the server's reason. - README step 2: the console snippet copies the token to the clipboard and prints a short confirmation. The user no longer has to select a 2,600-character string by hand. A note says to run it once at the console prompt. -- Integration version 0.3.5. It ships in one joint release with `add-keg-48180` and the companion card release. +- Integration version 0.4.4, synced with the companion card (both 0.4.4; major.minor in lockstep from here). It ships in one joint release with `add-keg-48180` and the companion card release. Not in scope: @@ -42,7 +42,7 @@ None. - `custom_components/perfectdraft/config_flow.py`: error mapping in `async_step_token`, and a return to the credentials form. - `custom_components/perfectdraft/strings.json`, `translations/en.json`: two new error keys. `invalid_auth` is reworded to include `{reason}`. - `README.md`: the step 2 snippet and wording. -- `manifest.json`: 0.3.5. +- `manifest.json`: 0.4.4. - `tests/`: a new stdlib-only test module for `authenticate()`. `test_config_flow.py` gains tests for the three error paths. - External: issues #11, #12 and #13. #12 and #13 are closed as duplicates of #11. #11 closes once the release ships. Credit goes to cesa030 for the root cause and fix, and to brettjenkins for the fork that confirmed it. - No config entry migration. Stored tokens have the same shape, so existing installs with a valid refresh token are unaffected. diff --git a/openspec/changes/fix-cognito-signin/tasks.md b/openspec/changes/fix-cognito-signin/tasks.md index 191e566..979be0d 100644 --- a/openspec/changes/fix-cognito-signin/tasks.md +++ b/openspec/changes/fix-cognito-signin/tasks.md @@ -22,12 +22,12 @@ ## 5. On-device verification and version -- [x] 5.1 Bump `manifest.json` to 0.3.5 (shared with `add-keg-48180`, which must not bump it again) +- [x] 5.1 Bump `manifest.json` to 0.4.4 (shared with `add-keg-48180`, which must not bump it again) - [x] 5.5 Run the full suite (`.venv-test/bin/pytest tests/` and `python3 -m unittest discover -s tests`) and confirm green ## Deferred: shipping without on-device checks -Maintainer decision, 2026-11-07: ship v0.3.5 without these on-device checks (no time for a Home Assistant reinstall). Coverage at release is the automated suite plus the README token verified in Firefox and Chromium; sign-in against the live service is untested. Run them after release; the open TODO is in `PROJECT_HYGIENE.md`. +Maintainer decision, 2026-11-07: ship v0.4.4 without these on-device checks (no time for a Home Assistant reinstall). Coverage at release is the automated suite plus the README token verified in Firefox and Chromium; sign-in against the live service is untested. Run them after release; the open TODO is in `PROJECT_HYGIENE.md`. - 5.2 Install the branch build on Home Assistant and add the integration from scratch with a fresh README token; confirm the entry is created and sensors populate - 5.3 With a deliberately wrong password, confirm the flow returns to the credentials form showing `invalid_credentials` and Cognito's reason; with a stale (>2 min) token, confirm `token_rejected` on the token form @@ -35,7 +35,7 @@ Maintainer decision, 2026-11-07: ship v0.3.5 without these on-device checks (no ## Workflow follow-up -- Release jointly with `add-keg-48180`: integration v0.3.5 and card v0.4.3, published together. Release notes credit cesa030 (root cause and fix in #11) and brettjenkins (fork that confirmed it). +- Release jointly with `add-keg-48180`: integration v0.4.4 and card v0.4.4, published together. Release notes credit cesa030 (root cause and fix in #11) and brettjenkins (fork that confirmed it). - After the release is live, comment on #11 with the release link and close it. - #12 and #13 are closed as duplicates of #11 (each with a thank-you comment) ahead of the release; post the release link there too. - Archive per `AGENTS.md` (merge, push, sync `api-client` and `config-flow` specs, archive, remove worktree and branch).