punimtag/ROADMAP.md

PunimTag roadmap

Living plan for product quality, auth/email reliability, and automation.

Now — shipped / in flight

• Fix public-host auth redirects (Kolby #57 family) — NEXTAUTH_URL + verify-email
• DEV mail trap via Mailpit (not Mailtrap SaaS / not Spamhaus-blocked Mailcow for e2e)
• Playwright e2e suite (e2e/) on @levkin/playkit against punimtagdev.levkin.ca
• Dedicated e2e user e2e@levkine.ca (Vault / Infisical / Gitea Actions)
• Vitest unit tests for viewer-frontend in Gitea Actions
• API smoke + Zod schema checks (health, people, tags, 401 contracts)
• storageState setup project + real upload smoke
• FastAPI e2e users — e2e (admin, mirrors e2e@levkine.ca) + e2e-viewer (viewer) in FastAPI main DB; E2E_API_USERNAME/PASSWORD + E2E_API_VIEWER_USERNAME/PASSWORD in CI
• Search / filter e2e — tag + person filters on public gallery (gallery.search-filters.spec.ts)
• Role permissions e2e — viewer vs admin write gates (api.role-permissions.spec.ts)
• ROADMAP (this file)

Next (near-term)

Ops / docs debt (do these before more feature e2e)

• Commit ansible FastAPI-e2e work — provision-punimtag-e2e-user.py (FastAPI upsert), punimtag-sync-smtp.py (quote fix), vault.example.yml, SECRETS.md, vaultwarden-sync.yml are live/tested but may still sit on a cluttered local branch — PR onto feat/mailpit-playkit-secrets or a clean cherry-pick branch
• Infisical /playkit/punimtag keys — create E2E_API_USERNAME/PASSWORD + E2E_API_VIEWER_* once in the UI (plaintext raw POST 422 on this Infisical build; Gitea Actions secrets are already set and are what CI uses)
• Vaultwarden sync — eval "$(make -s bw-unlock)"; make vault-sync-bitwarden GROUP=punimtag-e2e after ansible group entries land
• Wire QA/PROD SMTP on live guests when LXCs 9102/9103 exist (make punimtag-sync-smtp ENV=qa|prod)
• Stop seeding admin@admin.com in docs as the day-to-day login; keep bootstrap scripts but point operators at Vaultwarden PunimTag e2e

Playkit adoption (pin is v0.3.0 today)

Kit feature	In pin?	PunimTag use
Zod schema on ApiClient	yes	health + people/tags catalog only
saveStorageState / storageStateUse	yes	setup uses saveStorageState; specs use raw test.use({ storageState }) (storageStateUse optional cosmetic)
playkitFailureArtifacts()	yes	playwright.config.ts
Mailpit / createMailInbox	yes	mail specs
interceptNetworkCall / startNetworkErrorMonitor	no — HEAD only (post-v0.3.0)	not used — bump pin after playkit tags v0.3.1+
Timing → Pushgateway	yes API	not wired — needs make deploy-observability + CI PLAYKIT_METRICS_*

Highest-value new tests once pinned past v0.3.0:

1. startNetworkErrorMonitor on gallery / search / upload / manage-users — fail if the UI stays green while /api/search or NextAuth silently 5xxs (exclude expected 401s on public surfaces)
2. interceptNetworkCall on upload — replace brittle waitForResponse + text scrape with a typed spy on **/api/photos/upload (status + JSON shape)
3. interceptNetworkCall on search filter UI — assert the browser actually POSTs/GETs /api/search?tags= after checkbox click
4. Widen Zod schemas — /api/v1/auth/me, login TokenResponse, search response — after FastAPI login (already have tokens in CI)

Product / coverage gaps

• admin-frontend Vitest (or Playwright admin project)
• PROD smoke — health + public login page only (no mutating tests)
• Favorites filter e2e (logged-in only in FilterPanel) — uses storageState
• People filter UI e2e (logged-in) — counterpart to the public tag UI test
• Viewer (NextAuth) write gates — hasWriteAccess / non-admin auth-DB user if/when we provision one (today FastAPI role gates are covered; NextAuth admin vs write is thinner)

Later

• Proper DEV deploy (next start + CI image) instead of long-lived next dev
• Ansible/app_setup path aligned with /opt/punimtag/viewer-frontend/.env (not /srv/app)
• OpenAPI-driven contract suite (playkit / consumer)
• Multi-browser matrix (firefox/webkit)
• Hermes/Mattermost report on e2e failure
• Enable playkit timing metrics in CI once Pushgateway is live

Test map

Layer	Where	Status
Viewer unit	viewer-frontend Vitest	CI viewer-unit
Backend unit/integration	tests/ pytest	existing
E2E browser + mail	e2e/tests/*	CI e2e
E2E API (unauth + catalog)	e2e/tests/api.*	CI
E2E FastAPI authed	api.fastapi-login.spec.ts	CI (secrets set)
E2E role-permission gates	api.role-permissions.spec.ts	CI (secrets set)
E2E gallery search filters	gallery.search-filters.spec.ts	CI (public, no login)
E2E network silent-failure monitor	—	gap (needs playkit > v0.3.0)
Admin UI	—	gap
Timing metrics push	—	gap (ops + CI env)

See also: e2e/README.md, playkit ROADMAP.md / docs/NETWORK.md / docs/IDEAS.md.