docs(12-04): complete setup-wizard PWA plan — paused at human-verify checkpoint
This commit is contained in:
Lucas Berger
@@ -0,0 +1,202 @@
|
||||
---
|
||||
phase: 12-initial-setup-wizard
|
||||
plan: 04
|
||||
subsystem: pwa, ui, api-client
|
||||
tags: [react, vite, tanstack-query, tdd, setup-wizard, oidc, playwright]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 12-02
|
||||
provides: /api/setup/* routes (7 handlers, pre-auth mount)
|
||||
- phase: 12-03
|
||||
provides: first-login-claims (upsertUser D-08)
|
||||
provides:
|
||||
- apps/pwa/src/api/client.ts — 7 setup API functions + SetupAlreadyLockedError
|
||||
- apps/pwa/src/routes/SetupPage.tsx — standalone 4-step wizard + Terminal/Locked screens
|
||||
- apps/pwa/src/App.tsx — setupQuery gate + /setup route + redirect when unconfigured
|
||||
- apps/pwa/src/App.test.tsx — gate tests (both branches)
|
||||
- apps/pwa/src/routes/SetupPage.test.tsx — wizard unit tests
|
||||
- .planning/phases/12-initial-setup-wizard/12-UI-SPEC.md — revised (done in prior session 0f3c378)
|
||||
affects:
|
||||
- first-run operator experience (SETUP-01/SETUP-02)
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: [] # Zero new packages
|
||||
patterns:
|
||||
- TDD RED/GREEN cycle — SetupPage.test.tsx (RED gate eb84e6e) → SetupPage.tsx (GREEN 62d80f6)
|
||||
- setupQuery (staleTime: 0) alongside meQuery — always-fresh setup gate (mirrors D-10 spirit)
|
||||
- alreadyLocked prop pattern — SetupPage accepts prop to directly render Surface 8 (testable)
|
||||
- `window.history.pushState({}, '', '/')` in beforeEach — URL isolation between BrowserRouter tests
|
||||
- nested <Routes> inside route element — outer * route contains inner app-shell routes
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- apps/pwa/src/routes/SetupPage.tsx
|
||||
- apps/pwa/src/routes/SetupPage.test.tsx
|
||||
- apps/pwa/src/App.test.tsx
|
||||
modified:
|
||||
- apps/pwa/src/api/client.ts
|
||||
- apps/pwa/src/App.tsx
|
||||
- .planning/phases/12-initial-setup-wizard/12-UI-SPEC.md (prior session 0f3c378)
|
||||
|
||||
key-decisions:
|
||||
- "ALREADYLOCKED-PROP: SetupPage accepts alreadyLocked?: boolean prop to render Surface 8 directly — enables unit tests without needing a live 423 response; also handles the runtime case where any setup API call returns 423 mid-wizard"
|
||||
- "NESTED-ROUTES: App.tsx uses outer <Route path='*'> containing inner <Routes> to implement the gate — the /setup route is at the outer level (pre-gate) so it renders standalone before the gate logic runs"
|
||||
- "URL-ISOLATION: window.history.pushState({}, '', '/') in beforeEach resets BrowserRouter URL state between tests (jsdom shares window.location across tests in the same file)"
|
||||
|
||||
# Metrics
|
||||
duration: 32min
|
||||
completed: 2026-06-15
|
||||
---
|
||||
|
||||
# Phase 12 Plan 04: PWA Setup Wizard Summary
|
||||
|
||||
**Setup wizard PWA side: 7 API client functions, standalone 4-step SetupPage, App.tsx gate + /setup route; TDD; 236 tests pass; playwright-cli partial smoke pass**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 32 min
|
||||
- **Started:** 2026-06-15T18:20:37Z
|
||||
- **Completed:** 2026-06-15T18:55:00Z (at checkpoint Task 4)
|
||||
- **Tasks completed:** 3 of 4 (Task 4 is a human-verify checkpoint)
|
||||
- **Files modified:** 5
|
||||
|
||||
## Accomplishments
|
||||
|
||||
### Task 1: UI-SPEC Revision (pre-existing, 0f3c378)
|
||||
The UI-SPEC was revised in a prior planning session (commit 0f3c378). Verified all acceptance criteria pass:
|
||||
- No `/api/setup/generate` references (Generate Secrets step dropped per D-05)
|
||||
- Input fields for `oidc_issuer`, `oidc_client_id`, `vapid_public_key`, `app_external_url` present
|
||||
- Design system sections retained (Design System, Spacing Scale, Accessibility Contract)
|
||||
- Step indicator re-numbered to 4 steps (Welcome / Instance / Calendar / Complete)
|
||||
|
||||
### Task 2: Setup API Client + SetupPage Wizard (TDD RED/GREEN)
|
||||
|
||||
**RED gate (eb84e6e):** 17 failing tests covering all 7 API function exports and SetupPage rendering.
|
||||
|
||||
**GREEN (62d80f6):** Implemented:
|
||||
- `fetchSetupStatus()` — GETs `/api/setup/status`; no credentials/redirect:manual (pre-auth endpoint)
|
||||
- `postSetupConfig(payload)` — POSTs non-secret config (app_url, oidc_issuer, oidc_client_id, vapid_public_key)
|
||||
- `validateSetupDb()` — POSTs `/api/setup/validate/db`; typed error message on failure
|
||||
- `validateSetupOidc()` — POSTs `/api/setup/validate/oidc`; typed error message on failure
|
||||
- `validateSetupVapid()` — POSTs `/api/setup/validate/vapid`; typed error message on failure
|
||||
- `postSetupCredential(payload)` — POSTs fastmailEmail + appPassword to `/api/setup/credential`
|
||||
- `postSetupComplete()` — POSTs `/api/setup/complete`; throws SetupAlreadyLockedError on 423
|
||||
- `SetupAlreadyLockedError` — typed error class for 423 responses
|
||||
|
||||
**SetupPage.tsx:**
|
||||
- Standalone full-page wizard — no AppNav/BottomTabBar imports
|
||||
- `role="main"` on content column; `aria-live="polite"` on validation rows
|
||||
- 4 sub-components: StepIndicator, ValidationRow, ActionRow, step cards
|
||||
- Step 1 (Welcome): orientation text, "Before you start" note block, Continue button
|
||||
- Step 2 (Instance Configuration): 4 fields (App URL, OIDC issuer, client_id, VAPID public key); Save & Validate triggers sequential DB+OIDC validation; Continue appears only when both pass
|
||||
- Step 3 (Calendar Credential): email+password fields; CalDAV validation; Complete Setup button
|
||||
- Surface 7 (Terminal): ShieldCheck icon, "Setup complete" heading, Sign in link
|
||||
- Surface 8 (Already Locked): via `alreadyLocked` prop or any 423 response mid-wizard
|
||||
- All copy is plain-text JSX children — no HTML injection
|
||||
- Focus management: `stepHeadingRef.current.focus()` on step change (a11y)
|
||||
|
||||
### Task 3: App.tsx Gate + /setup Route (1587bca)
|
||||
|
||||
- Added `setupQuery = useQuery({ queryKey: ['setupStatus'], queryFn: fetchSetupStatus, retry: false, staleTime: 0 })`
|
||||
- Added `<Route path="/setup" element={<SetupPage />} />` at the outer Routes level (pre-gate)
|
||||
- Redirect gate: `setupLoading → <div aria-hidden>` | `setupComplete===false → <Navigate to="/setup">` | `true → full app shell`
|
||||
- `/setup` route renders standalone — AppNav/BottomTabBar only render inside the `setupComplete===true` branch
|
||||
|
||||
**App.test.tsx:**
|
||||
- `setupComplete: false` → SetupPage renders, AppNav absent ✓
|
||||
- `setupComplete: true` → CalendarShell renders, AppNav present ✓
|
||||
- Loading state → CalendarShell absent (no flash) ✓
|
||||
|
||||
### Task 4: playwright-cli Partial Smoke (CHECKPOINT — awaiting human)
|
||||
|
||||
playwright-cli Chromium verified (automated):
|
||||
- `/setup` renders standalone wizard: `role="main"`, h1 "FamilySync Setup", 4-step indicator ✓
|
||||
- No `<nav>` element on the wizard page ✓
|
||||
- Welcome step: heading, pre-start block, Continue button ✓
|
||||
- Clicking Continue advances to step 2 (Instance Configuration) ✓
|
||||
- Step 2: all 4 input fields with correct placeholders; Save & Validate button; Back button ✓
|
||||
- Step 1 shows completed checkmark in step indicator ✓
|
||||
|
||||
Screenshots saved:
|
||||
- `.planning/phases/12-initial-setup-wizard/screenshot-setup-welcome.png`
|
||||
- `.planning/phases/12-initial-setup-wizard/screenshot-setup-step2-config.png`
|
||||
|
||||
**Cannot be automated (requires human):**
|
||||
1. The Docker API container needs `docker compose build && docker compose up -d` to pick up Phase 12 Plan 02 setup routes — the running container is from an older build without `setup.js`
|
||||
2. Fresh/unconfigured DB (no `setup_complete`, no `member_credentials`) needed to verify the automatic redirect-to-/setup flow
|
||||
3. Live OIDC discovery validation (requires running Authelia reachable from the container)
|
||||
4. Live CalDAV credential validation (requires real Fastmail app password)
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: UI-SPEC revision** — `0f3c378` (prior session — docs)
|
||||
2. **Task 2 RED: failing tests** — `eb84e6e` (test)
|
||||
3. **Task 2 GREEN: client.ts + SetupPage** — `62d80f6` (feat)
|
||||
4. **Task 3: App.tsx gate + tests** — `1587bca` (feat)
|
||||
5. **Task 4: CHECKPOINT** — awaiting human verification
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `apps/pwa/src/api/client.ts` — 7 setup functions + SetupAlreadyLockedError appended
|
||||
- `apps/pwa/src/routes/SetupPage.tsx` — new (standalone wizard, 5 surfaces, 530 lines)
|
||||
- `apps/pwa/src/routes/SetupPage.test.tsx` — new (17 tests, RED gate + implementation tests)
|
||||
- `apps/pwa/src/App.tsx` — setupQuery + /setup route + redirect gate added
|
||||
- `apps/pwa/src/App.test.tsx` — new (6 tests covering both gate branches)
|
||||
- `.planning/phases/12-initial-setup-wizard/12-UI-SPEC.md` — revised (prior session 0f3c378)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] `require('./SetupPage.js')` pattern incompatible with Vitest ESM mode**
|
||||
- **Found during:** Task 2 test execution
|
||||
- **Issue:** RED test scaffolding used `require('./SetupPage.js')` inside test functions to import after mocks — but in Vitest's ESM mode this resolves at runtime and cannot find the `.tsx` source file
|
||||
- **Fix:** Changed to static `import { SetupPage } from './SetupPage.js'` at the top of the test file (mocks are hoisted via `vi.mock` so static imports work correctly)
|
||||
- **Files modified:** `apps/pwa/src/routes/SetupPage.test.tsx`
|
||||
- **Commit:** `62d80f6` (Task 2 GREEN)
|
||||
|
||||
**2. [Rule 1 - Bug] BrowserRouter URL state persists between tests in jsdom**
|
||||
- **Found during:** Task 3 App.test.tsx test run
|
||||
- **Issue:** `setupComplete:false` test redirected to `/setup`, leaving `window.location` at `/setup` for the `setupComplete:true` test. The `/setup` route matched the standalone SetupPage instead of the CalendarShell.
|
||||
- **Fix:** Added `window.history.pushState({}, '', '/')` in `beforeEach` to reset URL to root before each test
|
||||
- **Files modified:** `apps/pwa/src/App.test.tsx`
|
||||
- **Commit:** `1587bca` (Task 3)
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all wizard steps render from live state (no hardcoded empty values). The validation steps (DB, OIDC, CalDAV) require a live API to produce success states; the component correctly shows pending/success/failure per actual API responses.
|
||||
|
||||
## Threat Surface Scan
|
||||
|
||||
No new threat surface beyond what is explicitly modeled in the plan's threat_model:
|
||||
- T-12-13 (wizard never handles secrets): mitigated — no VAPID_PRIVATE_KEY or SESSION_SECRET inputs
|
||||
- T-12-14 (XSS via operator input): mitigated — no dangerouslySetInnerHTML in SetupPage.tsx (grep returns 0)
|
||||
- T-12-15 (app password disclosure): mitigated — type="password", never stored client-side
|
||||
- T-12-SC (new packages): mitigated — zero new npm packages
|
||||
|
||||
## TDD Gate Compliance
|
||||
|
||||
- RED gate: `eb84e6e` test commit (17 failing tests) — PRESENT ✓
|
||||
- GREEN gate: `62d80f6` feat commit (all tests pass) — PRESENT ✓
|
||||
- REFACTOR: no refactoring commit needed (implementation was clean on first pass)
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
Files exist:
|
||||
- `apps/pwa/src/api/client.ts` — FOUND
|
||||
- `apps/pwa/src/routes/SetupPage.tsx` — FOUND
|
||||
- `apps/pwa/src/routes/SetupPage.test.tsx` — FOUND
|
||||
- `apps/pwa/src/App.tsx` — FOUND
|
||||
- `apps/pwa/src/App.test.tsx` — FOUND
|
||||
|
||||
Commits exist:
|
||||
- `eb84e6e` — FOUND
|
||||
- `62d80f6` — FOUND
|
||||
- `1587bca` — FOUND
|
||||
|
||||
Test suite: 236 passed | 0 failed
|
||||
TypeCheck: clean (0 errors)
|
||||
Build: green (dist/sw.js emitted)
|
||||
playwright-cli: partial smoke pass (steps 1-2 verified headlessly; steps 3-4 require operator rebuild + fresh DB)
|
||||
Reference in New Issue
Block a user