Files
kandev/docs/plans/integration-watcher-save-state/plan.md
T
2026-08-24 11:09:03 +00:00

124 lines
5.1 KiB
Markdown

---
spec: docs/specs/ui/requirements/settings-manual-save.md
created: 2026-07-29
status: complete
---
# Implementation Plan: Integration Watcher Save State
## Overview
Watcher enabled-state saves pass through a shared frontend draft hook. GitHub
review-watch updates currently violate their frontend contract by returning an
acknowledgement instead of the updated watch, so the store does not advance and
the cleared draft reveals stale state. The repair aligns that endpoint with all
other watcher updates, makes the shared hook retain a clean saved baseline until
authoritative items reconcile, and proves the user-visible flow without a
refresh.
## Confirmed root cause
- `updateReviewWatch()` is typed as returning `ReviewWatch`, but
`httpUpdateReviewWatch` returns `{"updated": true}`.
- `useReviewWatches.update` forwards that acknowledgement to
`updateReviewWatch` in the Zustand slice. Because the response has no `id`,
the cached row is not replaced.
- `useWatcherEnabledDrafts.save` removes the successful local draft immediately.
When its `items` input is still stale, the rendered row falls back to the
pre-save `enabled` value until a reload fetches the persisted record.
- The shared hook is used by GitHub, GitLab, Jira, Linear, and Sentry watcher
settings, so it must tolerate delayed authoritative-list reconciliation.
## Backend
### GitHub review-watch update response
- Update `apps/backend/internal/github/controller.go` so
`httpUpdateReviewWatch` loads and returns the updated `ReviewWatch`, matching
the existing issue-watch handler and the TypeScript client contract.
- Add a focused HTTP regression in
`apps/backend/internal/github/controller_test.go` that updates `enabled` and
asserts the response contains the same watch `id` with the new value.
No database, authorization, or public route changes are required.
## Frontend
### Shared watcher saved baseline
- Update
`apps/web/components/integrations/use-watcher-enabled-drafts.ts` to distinguish
unsaved drafts from successfully persisted values that have not yet appeared
in `items`.
- Render and toggle against the latest saved baseline, keep the contributor
clean after a successful save, preserve edits made during an in-flight save,
and remove the temporary saved baseline once the authoritative item matches
or disappears.
- Extend
`apps/web/components/integrations/use-watcher-enabled-drafts.test.tsx` with
regressions for stale post-save items and later authoritative reconciliation.
### Mobile design contract
This is state reconciliation inside existing watcher tables and cards. It does
not change composition, navigation, overlays, scrolling, touch targets, or
viewport behavior. Desktop and mobile continue sharing the same watcher state
hook and action handlers. The nearest mobile exemplar is the existing GitLab
watch card in `mobile-gitlab-parity.spec.ts`, whose touch-sized pause control
already covers the shared mobile interaction.
## Tests
- **What:** GitHub review-watch update returns the authoritative updated row.
**File:** `apps/backend/internal/github/controller_test.go`.
**How:** SQLite-backed Gin handler test through the real controller/service/store.
- **What:** A successful watcher save stays visually changed and clean while
incoming items are stale, then reconciles when they catch up.
**File:**
`apps/web/components/integrations/use-watcher-enabled-drafts.test.tsx`.
**How:** Vitest hook harness under `SettingsSaveProvider`.
- **What:** Failed saves and in-flight newer edits remain dirty.
**File:**
`apps/web/components/integrations/use-watcher-enabled-drafts.test.tsx`.
**How:** retain and extend the existing failure/retry coverage as needed.
## E2E Tests
- **Scenario:** GIVEN an active GitHub review watch, WHEN the user pauses it and
saves, THEN the row stays Paused without reload; WHEN the user enables and
saves again, THEN it stays Active without reload.
**File:** `apps/web/e2e/tests/integrations/github-workspace-settings.spec.ts`.
**What to verify:** status text, clean Save changes state, and persisted API
value after each save.
- Run the existing mobile GitLab watcher pause scenario as change-aware proof
that the shared hook retains mobile capability and touch behavior.
## Implementation Tasks
1. [x] [Task 01: Return the updated GitHub review watch](task-01-github-review-watch-response.md)
2. [x] [Task 02: Reconcile shared watcher saved state](task-02-shared-watcher-saved-baseline.md)
3. [x] [Task 03: Prove pause and resume without refresh](task-03-watcher-save-e2e.md)
Execution is sequential in the primary conversation. No task is delegated
without explicit user authorization.
## Verification
After each task's targeted checks:
```bash
make fmt
make typecheck test lint
```
The E2E managed runner rebuilds backend and frontend production artifacts before
the focused Playwright checks.
## Risks
- Clearing a saved overlay too early recreates the flicker; retaining it forever
can mask a later authoritative update. Reconciliation therefore clears only
when the matching item reaches the saved value or the item disappears.
- Concurrent edits during Save must remain dirty and must not be replaced by
the completed request.