From 4b80fffe6729846329b8b1486b6c05c6c11245f8 Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 24 Sep 2026 00:11:34 -0400 Subject: [PATCH 1/3] release: advance version to 0.7.0 and add the admin PWA release notes --- RELEASE_NOTES.md | 102 ++++++++++++++++++++++ custom_components/nestquest/manifest.json | 2 +- pyproject.toml | 2 +- uv.lock | 2 +- 4 files changed, 105 insertions(+), 3 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 6504e5f..df2043a 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,5 +1,107 @@ # NestQuest Release Notes +## Version 0.7.0 — 2026-09-24 + +### Scope + +Seventh release of NestQuest, promoting the admin surface from `dev` onto +0.6.0: the standalone admin PWA and the admin-plane API work it depends on. + +- **Feature 19 — Admin PWA:** the parent-facing admin surface is now a + standalone mobile-first React progressive web app (`admin/`), implementing + `design/ADMIN-SPEC.md`: Authentik OIDC authorization-code + PKCE login with + an explicit refusal for a user outside `nestquest-admins`; an installable + PWA (manifest + service worker); and the Today, Definitions, Schedule and + History screens. Every mutating action goes through the API admin routes; + the API remains the security boundary (D-003/D-012). Today shows the + household snapshot; Definitions supports create/edit with multi-select + assignees, a recurrence rule with interval and per-window due times, a + skip-on-away toggle, a shipped Lucide icon subset and a backend-computed + occurrence preview; Schedule has a presence month grid (cycle position from + the anchor date, never ISO parity, D-004) and an override editor with a live + "removes N upcoming tasks" consequence count; History has All/Reversals/ + Missed filters, day-grouped rows, per-period stats, CSV export and the + append-only footer. Undo reverses a completion, and live updates arrive over + the admin SSE stream without a manual reload. (PRs #187–#210, plus the + feature-review fix #212.) +- **Feature 21 — Admin Today Snapshot API:** `GET /api/v1/admin/snapshot` + serves the Today view's household snapshot on the admin plane (reusing the + core snapshot builder with missed instances included, D-009). (PRs #190/#191.) +- **Feature 22 — Admin Definitions Read and skip_on_away:** + `GET /api/v1/admin/quest-definitions` lists all definitions (active and + inactive), and a persisted per-definition `skip_on_away` boolean is accepted + by create/update and honoured by materialization. Adds an optional + `assignee_child_ids` to the edit route so the PWA can reassign children. + (PRs #193, #194, #196, #197.) +- **Feature 23 — Admin API Completion (preview, presence, live):** a bounded + rule occurrence-preview route; presence-schedule and presence-override + reads; a live override consequence count computed from the same core + generator the materializer uses; and an admin-plane transition SSE stream + (`GET /api/v1/admin/events`) off the one in-process publisher. (PRs + #199–#203.) + +### Requirements + +- Minimum Home Assistant version: **2024.6.0**. +- A running NestQuest API service, reachable at the base URL and panel service + token configured in the integration options. The API service source ships in + `api/`; there is still **no container image, compose file or deployment + runbook in this release** because Feature 17 is not part of it. +- The admin PWA is built to run at `https://nestquest.cubecraftlabs.com` + behind Authentik; hosting it is part of the Feature 17 deployment, which is + **not** in this release. + +### Breaking changes + +- **Schema version advances 7 → 8.** Migration 8 adds the additive + `skip_on_away` column to `quest_definitions` (default 1, so every existing + definition keeps today's skip-when-absent behaviour). The migration runs on + the first start of this version. +- **Once migrated, a plain downgrade to 0.6.0 is impossible** — older builds + refuse a newer schema version. **Back up `nestquest.db` (plus `-wal`/`-shm`) + before upgrading**; see Rollback. +- No Home Assistant entity, service, event or automation surface changes in + this release. The API's new admin routes are additive. + +### Known Limitations + +- **Feature 17 (API deployment and identity) is not in this release.** There + is no API box, TLS reverse proxy, Authentik application/provider/ + `nestquest-admins` group, proven network separation, or backup/restore. The + integration and the admin PWA therefore cannot run end-to-end yet; Feature + 19's end-to-end Authentik/HTTPS acceptance remains **unverified** until + Feature 17 is deployed. +- **The admin PWA is not hosted.** `admin/` builds and is unit/integration + tested, but there is no deployment for it (it depends on Feature 17). +- **Feature 12's TouchHub/DAKOS runbook task remains physically unverified** + (needs the wall panel). +- Moving the household database from Home Assistant to the API box is a manual + file copy (the schema is unchanged by that move beyond the v8 migration). +- Single household; single API service. + +### Rollback + +**Schema version advances 7 → 8.** Migration 8 is additive, but a migrated +database **cannot** be read by 0.6.0 or earlier (they refuse a newer schema +version). **Back up `nestquest.db` (plus `-wal`/`-shm`) before upgrading.** To +return to 0.6.0 you must restore that backup; a plain downgrade is impossible +once migrated. + +**HACS installs:** + +1. Before upgrading, stop HA and back up `nestquest.db` (plus `-wal`/`-shm`) + from the HA config directory. +2. To roll back: HACS > Integrations > NestQuest > Redownload > 0.6.0, restore + the backed-up database, restart Home Assistant. + +**Manual installs:** + +1. Back up `nestquest.db` (plus `-wal`/`-shm`) before upgrading. +2. To roll back: replace `custom_components/nestquest/` with the 0.6.0 tree, + restore the backed-up database, restart Home Assistant. + +**Repository operators:** git-revert the 0.7.0 release merge on `main`. + ## Version 0.6.0 — 2026-09-23 ### Scope diff --git a/custom_components/nestquest/manifest.json b/custom_components/nestquest/manifest.json index 4f5d553..586303b 100644 --- a/custom_components/nestquest/manifest.json +++ b/custom_components/nestquest/manifest.json @@ -15,5 +15,5 @@ "iot_class": "local_polling", "issue_tracker": "https://github.com/Maniacs-Mansion/NestQuest/issues", "requirements": [], - "version": "0.6.0" + "version": "0.7.0" } diff --git a/pyproject.toml b/pyproject.toml index 88eaee7..3a208c8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "nestquest" -version = "0.6.0" +version = "0.7.0" description = "NestQuest Home Assistant Integration" readme = "README.md" requires-python = ">=3.11" diff --git a/uv.lock b/uv.lock index f3a2c88..04389dd 100644 --- a/uv.lock +++ b/uv.lock @@ -373,7 +373,7 @@ wheels = [ [[package]] name = "nestquest" -version = "0.6.0" +version = "0.7.0" source = { virtual = "." } [package.dev-dependencies] From 7969c164c41b69fc0566a2b2065db2438c97eb1a Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 24 Sep 2026 00:14:42 -0400 Subject: [PATCH 2/3] release: make the 0.7.0 rollback instructions API-host-aware The API service owns and migrates the database at NESTQUEST_DB_PATH on the API host; back up and restore it there, and scope the HACS/manual steps to the Home Assistant integration component only. Co-Authored-By: Claude Opus 5.5 --- RELEASE_NOTES.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index df2043a..25fbca3 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -83,22 +83,35 @@ Seventh release of NestQuest, promoting the admin surface from `dev` onto **Schema version advances 7 → 8.** Migration 8 is additive, but a migrated database **cannot** be read by 0.6.0 or earlier (they refuse a newer schema -version). **Back up `nestquest.db` (plus `-wal`/`-shm`) before upgrading.** To -return to 0.6.0 you must restore that backup; a plain downgrade is impossible -once migrated. +version). The database is owned and migrated by the **NestQuest API service**, +not by Home Assistant: it is the file at the API's configured +`NESTQUEST_DB_PATH` on the API host, which need not be anywhere near the Home +Assistant config directory. To return to 0.6.0 you must restore a backup of +that file taken before the upgrade; a plain downgrade is impossible once +migrated. -**HACS installs:** +**API host (database):** -1. Before upgrading, stop HA and back up `nestquest.db` (plus `-wal`/`-shm`) - from the HA config directory. -2. To roll back: HACS > Integrations > NestQuest > Redownload > 0.6.0, restore - the backed-up database, restart Home Assistant. +1. Before upgrading, stop the NestQuest API service and back up the database + file at its configured `NESTQUEST_DB_PATH`, plus its `-wal` and `-shm` + sidecars (`-wal`, `-shm`) if present. + Only then deploy 0.7.0 and start the API service, which applies migration 8. +2. To roll back: stop the API service, restore the backed-up database and + sidecars to `NESTQUEST_DB_PATH`, redeploy the API service at 0.6.0, and roll + back the Home Assistant integration to 0.6.0 (below). Then restart the API + service and Home Assistant. -**Manual installs:** +**Home Assistant integration — HACS installs** (integration component only; +the database lives with the API, see above): -1. Back up `nestquest.db` (plus `-wal`/`-shm`) before upgrading. -2. To roll back: replace `custom_components/nestquest/` with the 0.6.0 tree, - restore the backed-up database, restart Home Assistant. +1. To roll back: HACS > Integrations > NestQuest > Redownload > 0.6.0, then + restart Home Assistant. + +**Home Assistant integration — Manual installs** (integration component only; +the database lives with the API, see above): + +1. To roll back: replace `custom_components/nestquest/` with the 0.6.0 tree, + then restart Home Assistant. **Repository operators:** git-revert the 0.7.0 release merge on `main`. From 7887d16f11a43d541247b729134430c75fc536e8 Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 24 Sep 2026 10:02:16 -0400 Subject: [PATCH 3/3] release: include Feature 17 (API deployment) in the 0.7.0 notes --- RELEASE_NOTES.md | 48 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 25fbca3..8125b58 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -4,9 +4,21 @@ ### Scope -Seventh release of NestQuest, promoting the admin surface from `dev` onto -0.6.0: the standalone admin PWA and the admin-plane API work it depends on. +Seventh release of NestQuest, promoting the re-imagined architecture's admin +surface from `dev` onto 0.6.0: the API deployment and identity layer, the +admin-plane API work, and the standalone admin PWA that uses them. +- **Feature 17 — API Deployment and Identity:** the NestQuest API is packaged as + a container (`Dockerfile`, `deploy/compose.yaml`, pinned base image and exact + dependencies) and deployed behind a TLS reverse proxy (the shared Traefik, ACME + via the Cloudflare DNS-01 challenge); the Authentik application, OIDC provider + and `nestquest-admins` group are wired and the API validates the provider's + issuer/audience/JWKS (RS256); the panel plane is restricted to the Home + Assistant box while the admin plane is internet-facing behind Authentik; + continuous backup runs as a contained Litestream sidecar over SFTP to a NAS and + a restore is proven; a deployment runbook (`deploy/RUNBOOK.md`) and the + host-firewall unit (`deploy/systemd/nestquest-api-firewall.service`) ship. + (PRs #183, #214, #215, #216, #218.) - **Feature 19 — Admin PWA:** the parent-facing admin surface is now a standalone mobile-first React progressive web app (`admin/`), implementing `design/ADMIN-SPEC.md`: Authentik OIDC authorization-code + PKCE login with @@ -44,12 +56,14 @@ Seventh release of NestQuest, promoting the admin surface from `dev` onto - Minimum Home Assistant version: **2024.6.0**. - A running NestQuest API service, reachable at the base URL and panel service - token configured in the integration options. The API service source ships in - `api/`; there is still **no container image, compose file or deployment - runbook in this release** because Feature 17 is not part of it. -- The admin PWA is built to run at `https://nestquest.cubecraftlabs.com` - behind Authentik; hosting it is part of the Feature 17 deployment, which is - **not** in this release. + token configured in the integration options. The deployable ships in this + release: `Dockerfile`, `deploy/compose.yaml` (API + a contained Litestream + backup sidecar), `api/requirements.txt`, the host-firewall unit and + `deploy/RUNBOOK.md`. Deploying it needs a host, the DNS/TLS path and the + Authentik/Synology services described in the runbook. +- The admin PWA is built to run at `https://nestquest.cubecraftlabs.com` behind + Authentik. Serving the built `admin/` static bundle at that hostname is part of + the deployment described in the runbook. ### Breaking changes @@ -65,14 +79,16 @@ Seventh release of NestQuest, promoting the admin surface from `dev` onto ### Known Limitations -- **Feature 17 (API deployment and identity) is not in this release.** There - is no API box, TLS reverse proxy, Authentik application/provider/ - `nestquest-admins` group, proven network separation, or backup/restore. The - integration and the admin PWA therefore cannot run end-to-end yet; Feature - 19's end-to-end Authentik/HTTPS acceptance remains **unverified** until - Feature 17 is deployed. -- **The admin PWA is not hosted.** `admin/` builds and is unit/integration - tested, but there is no deployment for it (it depends on Feature 17). +- **The API and its identity/backup layer are deployed by the owner's + infrastructure, not by this release alone.** The deployment artifacts and + runbook ship here, but a running service still requires the host, the shared + reverse proxy, the Authentik application/provider/`nestquest-admins` group, the + backup target and the panel/admin network separation to be in place as the + runbook describes. +- **Serving the admin PWA is still outstanding.** `admin/` builds and is + unit/integration tested and the API it talks to is live, but the built static + bundle must still be hosted at `https://nestquest.cubecraftlabs.com` behind + Authentik; until then the PWA is not reachable end-to-end. - **Feature 12's TouchHub/DAKOS runbook task remains physically unverified** (needs the wall panel). - Moving the household database from Home Assistant to the API box is a manual