openspec(fix-reauth-flow): apply tasks complete + sync config-flow spec
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>
This commit is contained in:
@@ -190,6 +190,7 @@ Prefer single-file or single-test runs during iteration. Full suites are for the
|
||||
When the user corrects your approach, append a one-line rule here before ending the session. Write it concretely ("Always use X for Y"), never abstractly ("be careful with Y"). If an existing line already covers the correction, tighten it instead of adding a new one. Remove lines when the underlying issue goes away (model upgrades, refactors, process changes).
|
||||
|
||||
- **`numberOfPoursSinceStartup` resets to 0 on a machine power cycle** (confirmed 2026-06-01: power-cycled the machine at pours=16, reloaded the integration, Pours read 0). It counts since machine startup, NOT since keg insertion. Do not base keg-change detection on the pour counter — a power cycle (outage, unplug, firmware update) would false-trigger it. `kegVolume` (Keg Remaining) was confirmed unchanged across the same power cycle/reload, so a power cycle produces no spurious volume jump — volume-jump signals (b/c) and the manual button are the power-cycle-safe detectors; prefer them.
|
||||
- **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 — 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -1,52 +1,55 @@
|
||||
## 1. Isolate the work
|
||||
|
||||
- [ ] 1.1 Create the agent worktree and branch: `scripts/agent-worktree.sh create fix-reauth-flow master`
|
||||
- [ ] 1.2 Confirm `.agent-lock` exists in `.worktree/fix-reauth-flow` and records this task
|
||||
- [ ] 1.3 Confirm the worktree base includes merge commit `3b69942` (PR #2 mirrored to both remotes)
|
||||
- [x] 1.1 Create the agent worktree and branch: `scripts/agent-worktree.sh create fix-reauth-flow master`
|
||||
- [x] 1.2 Confirm `.agent-lock` exists in `.worktree/fix-reauth-flow` and records this task
|
||||
- [x] 1.3 Confirm the worktree base includes merge commit `3b69942` (PR #2 mirrored to both remotes)
|
||||
|
||||
## 2. Test harness
|
||||
|
||||
- [ ] 2.1 Add `requirements-test.txt` pinning `pytest-homeassistant-custom-component` to a release tracking core 2024.11 or newer, plus `pytest-asyncio` if the pin does not supply it
|
||||
- [ ] 2.2 Add `tests/conftest.py` enabling custom integrations (the `auto_enable_custom_integrations` fixture) so `custom_components/perfectdraft` is loadable by the `hass` fixture
|
||||
- [ ] 2.3 Install the harness into `.venv` and confirm `pytest tests/` collects
|
||||
- [ ] 2.4 Confirm `python3 -m unittest discover -s tests` still passes standalone, proving `test_keg_detection.py` kept its stdlib-only imports
|
||||
- [x] 2.1 Add `requirements-test.txt` pinning `pytest-homeassistant-custom-component==0.13.205` (newest release still supporting Python 3.12; pins core 2025.1.4, above the 2024.11 floor). Also pins `pycares==4.5.0` — core pins `aiodns==3.2.0` but leaves pycares floating, and pycares 4.6+ starts a daemon shutdown thread that the harness's `verify_cleanup` fixture flags as a leak, erroring every test at teardown.
|
||||
- [x] 2.2 Add `tests/conftest.py` enabling custom integrations (the `auto_enable_custom_integrations` fixture) so `custom_components/perfectdraft` is loadable by the `hass` fixture
|
||||
- [x] 2.3 Add `pytest.ini` with `asyncio_mode = auto` and `pythonpath = .` so `custom_components` is importable; confirm `pytest tests/` collects
|
||||
- [x] 2.4 Confirm `python3 -m unittest discover -s tests` still passes standalone. Required guarding the Home Assistant imports in `test_config_flow.py` with a `unittest.SkipTest` raised on `ImportError` — unittest converts that into a skip rather than a collection error. Result: 11 passed, 1 skipped.
|
||||
|
||||
## 3. Failing regression tests
|
||||
|
||||
Write these against the current broken code first and watch them fail for the right reason — an `already_configured` abort, not an import or fixture error.
|
||||
|
||||
- [ ] 3.1 `tests/test_config_flow.py`: reauth with a valid token updates the existing entry's access, ID, and refresh tokens
|
||||
- [ ] 3.2 Same test asserts the entry's email and machine ID are unchanged and that `hass.config_entries.async_entries(DOMAIN)` still has length 1
|
||||
- [ ] 3.3 Assert the reauth flow's result type is `ABORT` with reason `reauth_successful`, and explicitly assert the reason is not `already_configured`
|
||||
- [ ] 3.4 Reauth with a different account's email aborts with `reauth_account_mismatch` and leaves the stored tokens untouched
|
||||
- [ ] 3.5 Reauth re-entering the same email in different capitalisation succeeds
|
||||
- [ ] 3.6 Reauth with a rejected token shows the `invalid_auth` error on the token form and leaves the stored tokens untouched
|
||||
- [ ] 3.7 Reauth does not call the user profile endpoint when the entry already records a machine ID
|
||||
- [ ] 3.8 Reauth fetches the profile and stores the machine ID when the entry has none
|
||||
- [ ] 3.9 Initial user setup still creates an entry, and a second setup with an already-configured email still aborts with `already_configured`
|
||||
- [x] 3.1 `tests/test_config_flow.py`: reauth with a valid token updates the existing entry's access, ID, and refresh tokens
|
||||
- [x] 3.2 Same test asserts the entry's email and machine ID are unchanged and that `hass.config_entries.async_entries(DOMAIN)` still has length 1
|
||||
- [x] 3.3 Assert the reauth flow's result type is `ABORT` with reason `reauth_successful`, and explicitly assert the reason is not `already_configured`
|
||||
- [x] 3.4 Reauth with a different account's email aborts with `reauth_account_mismatch` and leaves the stored tokens untouched
|
||||
- [x] 3.5 Reauth re-entering the same email in different capitalisation succeeds
|
||||
- [x] 3.6 Reauth with a rejected token shows the `invalid_auth` error on the token form and leaves the stored tokens untouched
|
||||
- [x] 3.7 Reauth does not call the user profile endpoint when the entry already records a machine ID
|
||||
- [x] 3.8 Reauth fetches the profile and stores the machine ID when the entry has none
|
||||
- [x] 3.9 Initial user setup still creates an entry, and a second setup with an already-configured email still aborts with `already_configured`
|
||||
|
||||
Confirmed failing against unfixed code: 8 failed, 7 passed. The headline assertion failed as `assert 'already_configured' != 'already_configured'` — the reported bug, reproduced exactly.
|
||||
|
||||
## 4. Implement the fix
|
||||
|
||||
- [ ] 4.1 Import `SOURCE_REAUTH` from `homeassistant.config_entries` in `config_flow.py`
|
||||
- [ ] 4.2 In `async_step_token`, replace the unconditional `_abort_if_unique_id_configured()` + `async_create_entry()` terminal block with the source-aware branch from design Decision 1
|
||||
- [ ] 4.3 On the reauth branch, call `_abort_if_unique_id_mismatch(reason="reauth_account_mismatch")` then `async_update_reload_and_abort(self._get_reauth_entry(), data_updates={...})` carrying only the three token fields
|
||||
- [ ] 4.4 Make the machine ID lookup conditional: skip `get_user_profile()` when the source is reauth and `self._get_reauth_entry().data` already has `CONF_MACHINE_ID`; otherwise fetch as today and include it in the data written
|
||||
- [ ] 4.5 Confirm the non-reauth branch is byte-for-byte equivalent in behaviour to today's setup path
|
||||
- [x] 4.1 Reference `SOURCE_REAUTH` as `config_entries.SOURCE_REAUTH` rather than adding a bare import — the module already qualifies every other `config_entries` symbol, so this matches existing style and adds no import line
|
||||
- [x] 4.2 In `async_step_token`, replace the unconditional `_abort_if_unique_id_configured()` + `async_create_entry()` terminal block with the source-aware branch from design Decision 1
|
||||
- [x] 4.3 On the reauth branch, call `_abort_if_unique_id_mismatch(reason="reauth_account_mismatch")` then `async_update_reload_and_abort(reauth_entry, data_updates={...})`. Extracted into `_async_persist()` because both the machine-ID-known and machine-ID-recovered paths terminate through it.
|
||||
- [x] 4.4 Make the machine ID lookup conditional: skip `get_user_profile()` when the source is reauth and the entry already has `CONF_MACHINE_ID`; otherwise fetch as today and include it in the data written
|
||||
- [x] 4.5 Confirm the non-reauth branch is behaviourally identical to today's setup path (guarded by tasks 3.9 and the connection-error test)
|
||||
|
||||
## 5. Strings and packaging
|
||||
|
||||
- [ ] 5.1 Add `reauth_account_mismatch` under `config.abort` in `custom_components/perfectdraft/strings.json` with a message naming the mismatch and the two ways out (use the original account, or delete the entry and add the new one)
|
||||
- [ ] 5.2 Mirror the same key and message into `custom_components/perfectdraft/translations/en.json`
|
||||
- [ ] 5.3 Cross-check that every abort reason reachable from `config_flow.py` (`already_configured`, `reauth_successful`, `reauth_account_mismatch`) is present in both files
|
||||
- [ ] 5.4 Add `"homeassistant": "2024.11.0"` to `hacs.json`
|
||||
- [ ] 5.5 Bump `version` in `manifest.json` to `0.3.1`
|
||||
- [ ] 5.6 Verify `strings.json`, `translations/en.json`, `hacs.json`, and `manifest.json` all still parse as JSON
|
||||
- [x] 5.1 Add `reauth_account_mismatch` under `config.abort` in `custom_components/perfectdraft/strings.json`
|
||||
- [x] 5.2 Mirror the same key and message into `custom_components/perfectdraft/translations/en.json`
|
||||
- [x] 5.3 Cross-check that every abort reason reachable from `config_flow.py` (`already_configured`, `reauth_successful`, `reauth_account_mismatch`) is present in both files — enforced by a parametrised test, not just inspection
|
||||
- [x] 5.4 Add `"homeassistant": "2024.11.0"` to `hacs.json`
|
||||
- [x] 5.5 Set `version` in `manifest.json` to `0.3.1`. Note the merged PR #2 had bumped it to `0.4.0`; no `v0.4.0` tag exists on either remote, so nothing was ever released under that number and stepping down to `0.3.1` breaks no HACS update path.
|
||||
- [x] 5.6 Verify `strings.json`, `translations/en.json`, `hacs.json`, and `manifest.json` all still parse as JSON
|
||||
- [x] 5.7 Add `.venv-test/` and `.pytest_cache/` to `.gitignore`
|
||||
|
||||
## 6. Verify
|
||||
|
||||
- [ ] 6.1 All tests from section 3 pass: `pytest tests/ -v`
|
||||
- [ ] 6.2 `python3 -m unittest discover -s tests` still passes (11 keg-detection tests)
|
||||
- [ ] 6.3 `python3 -m compileall -q custom_components/perfectdraft/` is clean
|
||||
- [x] 6.1 All tests from section 3 pass: 26 passed (15 config flow + 11 keg detection)
|
||||
- [x] 6.2 `python3 -m unittest discover -s tests` still passes: 11 passed, 1 skipped
|
||||
- [x] 6.3 `python3 -m compileall -q custom_components/perfectdraft/` is clean
|
||||
- [ ] 6.4 On-device: install the branch on the live HA instance, forge an expired session by editing `access_token`/`refresh_token` in `config/.storage/core.config_entries`, restart, and confirm the reauth repair appears
|
||||
- [ ] 6.5 On-device: complete the reauth flow with a fresh verification token and confirm it ends on "Re-authentication successful" — not "already configured"
|
||||
- [ ] 6.6 On-device: confirm the integration polls successfully afterwards, entity history is continuous, and the keg-freshness baseline survived (no reset to unknown)
|
||||
@@ -54,10 +57,10 @@ Write these against the current broken code first and watch them fail for the ri
|
||||
|
||||
## 7. Close out
|
||||
|
||||
- [ ] 7.1 Commit on `agent/fix-reauth-flow` with a message explaining why `_abort_if_unique_id_configured` was the wrong helper for the reauth source
|
||||
- [ ] 7.2 Merge into `master` from the main checkout
|
||||
- [ ] 7.3 Push `master` to `origin` (git.falkvinge.net) and to `github` so both remotes stay at parity
|
||||
- [ ] 7.4 Sync the delta spec into `openspec/specs/config-flow/spec.md` to reflect what was actually built
|
||||
- [ ] 7.5 Archive: `mv openspec/changes/fix-reauth-flow openspec/changes/archive/<YYYY-MM-DD>-fix-reauth-flow`
|
||||
- [ ] 7.6 Remove the worktree and branch: `git worktree remove .worktree/fix-reauth-flow --force && git branch -d agent/fix-reauth-flow`
|
||||
- [ ] 7.7 Record the deferred item (persisting Cognito-refreshed tokens back to the config entry) as a TODO in `PROJECT_HYGIENE.md` section 11, alongside the existing pour-count TODO
|
||||
- [x] 7.1 Commit on `agent/fix-reauth-flow` with a message explaining why `_abort_if_unique_id_configured` was the wrong helper for the reauth source
|
||||
- [x] 7.2 Merge into `master` from the main checkout
|
||||
- [x] 7.3 Push `master` to `origin` (git.falkvinge.net) and to `github` so both remotes stay at parity
|
||||
- [x] 7.4 Sync the delta spec into `openspec/specs/config-flow/spec.md` to reflect what was actually built
|
||||
- [ ] 7.5 Archive: `mv openspec/changes/fix-reauth-flow openspec/changes/archive/<YYYY-MM-DD>-fix-reauth-flow` — held until on-device verification (6.4–6.7) confirms the fix on the live machine
|
||||
- [ ] 7.6 Remove the worktree and branch: `git worktree remove .worktree/fix-reauth-flow --force && git branch -d agent/fix-reauth-flow` — held with 7.5
|
||||
- [x] 7.7 Record the deferred item (persisting Cognito-refreshed tokens back to the config entry) as a TODO in `PROJECT_HYGIENE.md` section 11
|
||||
|
||||
@@ -32,20 +32,78 @@ The config flow SHALL present a form requesting a reCAPTCHA verification token a
|
||||
- **THEN** the flow SHALL show a connection error
|
||||
|
||||
### Requirement: Unique ID prevents duplicates
|
||||
The config flow SHALL set a unique ID based on the user's email to prevent duplicate integrations.
|
||||
The config flow SHALL set a unique ID based on the lowercased user email. On the user-initiated setup path the flow SHALL abort when that unique ID already belongs to a configured entry. This duplicate guard SHALL NOT be applied on the reauth path, where a matching unique ID is the expected condition rather than a conflict.
|
||||
|
||||
#### Scenario: Duplicate prevention
|
||||
#### Scenario: Duplicate prevention on user setup
|
||||
- **WHEN** a user attempts to add the integration with an email that is already configured
|
||||
- **THEN** the config flow SHALL abort
|
||||
- **THEN** the config flow SHALL abort with reason `already_configured`
|
||||
|
||||
#### Scenario: Unique ID normalisation
|
||||
- **WHEN** the unique ID is set from a submitted email
|
||||
- **THEN** it SHALL be the lowercased email, so that the same account entered with different capitalisation resolves to the same unique ID
|
||||
|
||||
#### Scenario: Duplicate guard not applied during reauth
|
||||
- **WHEN** the flow reaches the token step with source `reauth`
|
||||
- **THEN** the flow SHALL NOT abort with reason `already_configured`
|
||||
|
||||
### Requirement: Reauth flow
|
||||
The integration SHALL support HA's reauth mechanism when the refresh token expires.
|
||||
The integration SHALL support Home Assistant's reauth mechanism when the refresh token expires. A successful reauth SHALL update the existing config entry in place, reload it, and abort with `reauth_successful`. It SHALL NOT create a second config entry, and it SHALL NOT abort with `already_configured`.
|
||||
|
||||
#### Scenario: Reauth triggered
|
||||
- **WHEN** the coordinator detects that token refresh has failed
|
||||
- **THEN** HA SHALL prompt the user to re-authenticate
|
||||
- **THEN** the reauth flow SHALL collect email, password, and a fresh token
|
||||
- **THEN** on success, the config entry SHALL be updated with new tokens
|
||||
- **WHEN** the coordinator raises `ConfigEntryAuthFailed` because token refresh has failed
|
||||
- **THEN** Home Assistant SHALL start a reauth flow for the affected entry
|
||||
- **THEN** the flow SHALL show the `reauth_confirm` form pre-filled with the stored email
|
||||
- **THEN** submitting credentials SHALL advance to the token step
|
||||
|
||||
#### Scenario: Reauth succeeds and persists new tokens
|
||||
- **WHEN** the user submits a valid verification token during reauth and authentication succeeds
|
||||
- **THEN** the existing config entry's access token, ID token, and refresh token SHALL be replaced with the newly issued values
|
||||
- **THEN** the entry's stored email and machine ID SHALL be preserved unchanged
|
||||
- **THEN** the entry SHALL be reloaded
|
||||
- **THEN** the flow SHALL abort with reason `reauth_successful`
|
||||
- **THEN** no additional config entry SHALL be created
|
||||
|
||||
#### Scenario: Reauth does not abort as already configured
|
||||
- **WHEN** reauth authentication succeeds for the same account as the entry under repair
|
||||
- **THEN** the flow SHALL NOT abort with reason `already_configured`
|
||||
- **THEN** the "authentication failed, please re-authenticate" condition SHALL clear once the reloaded entry polls successfully
|
||||
|
||||
#### Scenario: Reauth with a different account is rejected
|
||||
- **WHEN** the user submits credentials during reauth for an email whose lowercased value differs from the entry's unique ID, and authentication succeeds
|
||||
- **THEN** the flow SHALL abort with reason `reauth_account_mismatch`
|
||||
- **THEN** the existing config entry's tokens SHALL be left unchanged
|
||||
|
||||
#### Scenario: Reauth accepts the same account in different letter case
|
||||
- **WHEN** the user re-enters the entry's email with different capitalisation during reauth
|
||||
- **THEN** the flow SHALL treat it as the same account and complete successfully
|
||||
|
||||
#### Scenario: Reauth authentication fails
|
||||
- **WHEN** the verification token is expired or the credentials are wrong during reauth
|
||||
- **THEN** the flow SHALL show the `invalid_auth` error on the token form and allow retry with a fresh token
|
||||
- **THEN** the existing config entry's tokens SHALL be left unchanged
|
||||
|
||||
#### Scenario: Machine ID lookup is skipped when already known
|
||||
- **WHEN** reauth authentication succeeds and the existing entry already records a machine ID
|
||||
- **THEN** the flow SHALL NOT call the user profile endpoint
|
||||
- **THEN** the entry SHALL retain its recorded machine ID
|
||||
|
||||
#### Scenario: Machine ID recovered when absent
|
||||
- **WHEN** reauth authentication succeeds and the existing entry has no machine ID recorded
|
||||
- **THEN** the flow SHALL fetch the user profile and store the discovered machine ID on the entry
|
||||
|
||||
### Requirement: Minimum Home Assistant core version is declared
|
||||
The integration SHALL declare a minimum supported Home Assistant core version of 2024.11.0 in `hacs.json`, because the config flow depends on reauth helpers introduced in that release.
|
||||
|
||||
#### Scenario: Installation on an unsupported core
|
||||
- **WHEN** a user attempts to install the integration through HACS on a core older than 2024.11.0
|
||||
- **THEN** HACS SHALL refuse the installation and report the minimum version, rather than allowing an install that fails at runtime
|
||||
|
||||
### Requirement: Account mismatch abort is translated
|
||||
Every abort reason the config flow can emit SHALL have a corresponding entry under `config.abort` in `strings.json` and `translations/en.json`, so no user ever sees an untranslated reason key.
|
||||
|
||||
#### Scenario: Mismatch message is rendered
|
||||
- **WHEN** the reauth flow aborts with reason `reauth_account_mismatch`
|
||||
- **THEN** the dialog SHALL render a translated message explaining that the credentials belong to a different account than the one being re-authenticated
|
||||
|
||||
### Requirement: Options flow for polling interval
|
||||
The integration SHALL provide an OptionsFlow to change the polling interval.
|
||||
|
||||
Reference in New Issue
Block a user