Starts the contact form feature: AI-DLC inception and design, dev proxy for /api

Adds the contact-form-cms feature docs (requirements, execution plan,
functional and infrastructure design, code generation plan) and an optional
Vite dev proxy for /api through API_PROXY_TARGET.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 23:04:16 +01:00
co-authored by Claude Sonnet 5.5
parent 7d594ffa1d
commit 4da314c0ba
10 changed files with 490 additions and 1 deletions
@@ -0,0 +1,48 @@
# Execution plan: contact-form-cms
## Summary
Single unit of work (web only): connect the ASF contact form to the CMS contact module through the copied headless package, with Friendly Captcha, CSP and dev proxy. Server work and the package captcha slot are delivered by other sessions.
## Stages
| Stage | Decision | Reason |
|---|---|---|
| Workspace Detection | Done | Brownfield, Feature |
| Reverse Engineering | Skip | Team agreement |
| Requirements Analysis | Done (approved by SLS-Main for Bryan) | |
| User Stories | Skip | One persona (visitor); acceptance in requirements |
| Workflow Planning | This document | |
| Application Design | Skip | No new components; ContactForm, Gate and Panel are adapted. The package boundary is fixed by the package |
| Units Generation | Skip | One unit: `contact-form` |
| Functional Design | Execute | State machine of gate, availability, captcha and submit; field mapping; preselect; accessibility; error handling |
| NFR Requirements | Skip | Covered in the requirements (security, performance, testing); Security Baseline is enforced at each stage |
| NFR Design | Skip | Merged into functional and infrastructure design |
| Infrastructure Design | Execute | CSP directives (captcha), Vite dev proxy, deploy impact, pipeline, rollback |
| Code Generation | Execute | Plan first; approval before code (SLS-Main for Bryan; push and merge stay with Bryan) |
| Build and Test | Execute | Unit, component, PBT, e2e with mocks, manual run against the temporary environment, Lighthouse |
| Operations | Execute (included) | Deployment notes, monitoring (events only, no personal data), production readiness checklist; production stays off until Bryan's go |
## Sequence and dependencies
```mermaid
flowchart LR
RA[Requirements<br/>done] --> WP[Workflow Planning]
WP --> FD[Functional Design]
FD --> ID[Infrastructure Design]
ID --> CG[Code Generation<br/>plan then code]
CG --> BT[Build and Test]
BT --> OP[Operations]
PK[Package with captcha slot<br/>SLP Software - SLS - Main] -.final copy.-> CG
SV[Server verifier and ASF host<br/>SLS Software - CMS / AndreaSlopFotografie] -.real test.-> BT
classDef done fill:#9ae6b4,stroke:#2f855a,color:#000;
classDef todo fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef ext fill:#f6e05e,stroke:#c05621,color:#000;
class RA done;
class WP,FD,ID,CG,BT,OP todo;
class PK,SV ext;
```
Text alternative: requirements are done; planning, functional design, infrastructure design, code generation, build and test and operations follow in order; the package slot and the server work from other sessions feed code generation and the real test.
## Gates
- Design and plan approvals go to SLP Software - SLS - Main (acts for Bryan within the agreed frame).
- Push, merge, deploy, production and choices about design, text or privacy stay with Bryan.
- No code before the code generation plan is approved. The final package is copied only after SLS-Main's message.
@@ -0,0 +1,56 @@
# Requirements clarification: contact-form-cms
Questions were asked interactively in chat (project agreement); answers recorded here afterwards. Open follow-up questions are routed through the session "SLP Software - SLS - Main" (Bryan's instruction, 2026-11-10).
## Question 1: Security Baseline extension
- A) Yes, enforce
- B) No
[Answer]: A
## Question 2: Property-based testing extension
- A) Full
- B) Partial (pure functions and round-trips)
- C) No
[Answer]: B
## Question 3: Operations phase
- A) Yes, include now
- B) Decide later
- C) No
[Answer]: A
## Question 4: Relation between the cms-client package and the existing ASF form
- A) Package replaces state and validation; the existing ContactForm UI stays and uses useContactForm
- B) Package only for sending
[Answer]: A
## Question 5: Subject
- A) Select value (id) is the subject
- B) Free text
- X) Other
[Answer]: X - The human-readable label ("Newborn shoot", "Overig") is sent as `subject`; the id stays local for the ?pakket= preselect. (Decision by Bryan, relayed by SLP Software - SLS - Main)
## Question 6: Robot check
- A) None now
- B) Friendly Captcha now
- X) Other
[Answer]: B - Build Friendly Captcha now (Bryan via SLP Software - SLS - Main). Package gets a captcha slot (SLS-Main), server verifier by SLS Software - CMS, widget + CSP + privacy text by this feature.
## Question 7: Form unavailable
- A) Mailto block instead of "Binnenkort"
- B) Keep the dimmed "Binnenkort" view
- X) Other
[Answer]: B - Keep the existing dimmed "Binnenkort" gate (Bryan).
## Question 8: Testing against the server
- A) Mocks in CI + manual check against the temporary environment
- B) Mocks only
[Answer]: A
@@ -0,0 +1,44 @@
# Requirements: contact-form-cms
## Intent analysis
- **User request**: Build the own contact form for Andrea Slop Fotografie on the CMS contact module, using the headless `cms-client` package from the SlpSoftware repo (read only, copied here).
- **Request type**: New feature on existing code (brownfield). Replaces the "no back-end yet" stub from `contact-page`.
- **Scope**: Web repo only (components, content, CSP, dev proxy, tests, docs). Server work is requested from other sessions, not built here.
- **Complexity**: Moderate to complex: public endpoint with personal data, captcha, prerender/hydration constraints, cross-session contract.
- **Depth**: Standard, security-relevant. User Stories skipped (one persona: the visitor).
## Decisions (see requirement-verification-questions.md)
Security Baseline: enforced. PBT: partial (PBT-02, 03, 07, 08, 09). Operations: included. Package replaces the form's own state and validation. Subject is the readable label. Friendly Captcha built now. Gate stays the dimmed "Binnenkort" view. Tests: mocks in CI plus manual against the temporary environment.
## Functional requirements
- **FR-CF-01 Package**: Copy `src/cms-client/` (http/, contact/, README, boundary test) into `web/src/cms-client/`. It stays headless and imports nothing from the app (boundary test plus ESLint rule). The copy is kept in sync with the SlpSoftware original; no local forks of its logic.
- **FR-CF-02 Logic**: `useContactForm` drives the existing Chakra skin (fields, select, PrivacyNote, success state with `replyTime`). The old `contactFormReducer`, own validation and the `submitContactForm` stub are removed or reduced to a thin mapping.
- **FR-CF-03 Field mapping**: naam to name (max 100), email to email (254), shoot to subject (the readable label, 1-100, e.g. "Newborn shoot", "Overig"), bericht to message (2000). The package id stays local for the `?pakket=` preselect. Messages are the package's NL messages.
- **FR-CF-04 Availability (progressive enhancement)**: The prerendered/initial render is the gate ("Binnenkort"). After hydration and when the form scrolls into view (IntersectionObserver) the client calls `GET /api/v1/contact-messages/token`; only on `200` (and a captcha provider this site supports) does the form become active. Any other result (404 form closed, 429, 5xx, network, unsupported captcha) keeps the gate. `siteContent.contactForm.enabled` stays as an extra static kill switch (default false until Bryan's go). When it is `false`, the client makes NO token request at all (no network traffic, no server cost). The token is fetched lazily when the form comes into view (IntersectionObserver); first focus is only the fallback where IntersectionObserver is missing.
- **FR-CF-05 Layout stability**: No layout shift on upgrade; the existing placeholder heights stay valid. No token, widget or e-mail address in the prerendered HTML.
- **FR-CF-06 Submit**: `POST /api/v1/contact-messages` with `Idempotency-Key`, honeypot `hpCheck` (client side only the honeypot; the 3 s browser time check is dropped, the server enforces `minSeconds` through the token), one automatic token refresh on `errors.token = expired`, `202` means success. Server field errors map to the fields; focus moves after render (inputs are disabled while sending). Error messages are not placed inside `<label>`.
- **FR-CF-07 Failure**: 429, 5xx, 503 or network errors give a generic failure message with the mailto fallback; visitors never see technical text. The 429 message comes from the package (Retry-After in minutes), no own text. The mailto fallback after a failed send keeps the address out of the HTML (the `useEmailAddress` approach stays).
- **FR-CF-08 Preselect**: A package chosen via a "Boek..." link before the form has mounted is not lost: `ContactPanel` remembers the last preselect and passes it as initial value.
- **FR-CF-09 Captcha (Friendly Captcha)**: When the token endpoint returns `captcha = {provider, siteKey}`, the widget is shown client-only after hydration in a reserved height, its token goes to `captchaToken`, and it resets on expiry. The package provides the slot (SLP Software - SLS - Main), the server verifies (SLS Software - CMS); this feature builds the widget, loads it only when needed, and adds the CSP entries for the exact provider and version. Fail-open on a provider outage is a server decision already taken.
- **FR-CF-10 Privacy**: The privacy statement names the captcha provider and what the form stores. No personal data in logs, Sentry or Umami; only the events `contact-sent` and `contact-failed`.
- **FR-CF-11 Dev proxy**: Vite dev proxy for `/api` to the temporary environment (`http://192.168.1.2:5290`). Production is same-origin through the host/IIS proxy; no CORS.
- **FR-CF-12 Accessibility**: Labelled fields, focus handling for errors, live region for success/failure, honeypot hidden from assistive tech, keyboard operable, widget with reserved height.
## Non-functional requirements
- **NFR-CF-01 Security** (Security Baseline enforced): CSP `connect-src 'self'` plus captcha origins only (script/frame entries per provider and version, nothing wider); no secrets in the client (the siteKey is public); no personal data, tokens or idempotency keys logged; input limits identical to the server; honeypot and idempotency handled; dependency audit stays clean.
- **NFR-CF-02 Performance**: No new JS on pages without a form in view; the captcha script loads only when the form is active; Lighthouse budgets of `lighthouserc.cjs` stay green.
- **NFR-CF-03 Testing**: Unit and component tests for mapping, gate states, preselect and submit paths with a mocked API; fast-check on mapping/validation round-trips (PBT-02/03/07/08/09); e2e with a mocked `/api` route; manual verification against the temporary environment (CMS 192.168.1.2:5175, API :5290, smtp4dev :5301) with evidence in the construction docs. Tests of the old reducer are replaced. Extra cases: an unknown or missing captcha provider keeps the gate; an expired captcha token is never sent; every subject label is 1-100 characters and a label containing & ' " < > does not break the payload (mail encoding is server-side, the payload is tested here).
- **NFR-CF-04 Compatibility**: Works with hydration of the prerendered site (PR #14); no hydration mismatch; with JS off the gate and the mail button show.
- **NFR-CF-05 Operations**: CSP and dev-proxy changes deploy through the existing pipeline; production stays off (`enabled: false`) until Bryan's explicit go; rollback is switching `enabled` off; checklist in the Operations phase.
## Out of scope / asked of others
- Server module, captcha verifier, openapi (SLS Software - CMS); package captcha slot (SLP Software - SLS - Main).
- Per-site server config for ASF: `Contact__RecipientEmail` (env only), sender in `Email:AllowedFromAddresses`, `ForwardedHeaders:KnownProxies`/`ClientPartitionKey` on IIS, `Contact:Enabled`, `MinSeconds`, retention, CMS switch (session `AndreaSlopFotografie`, routed by SLP Software - SLS - Main).
- ASF production hosting (IIS) and the production go-live.
## Resolved with SLP Software - SLS - Main (approved on behalf of Bryan, 2026-11-10)
1. Lazy token fetch via IntersectionObserver (first focus only as fallback).
2. Friendly Captcha: provisionally v2 (bundled SDK, script-src 'self'; API origin https://global.frcapi.com in connect-src and possibly frame-src; possibly worker-src blob: and 'wasm-unsafe-eval'). Final directives per version come from CMS-U9 and a test in a real browser; no wildcards.
3. Labels come from the existing shoot options in content; the label of "Overig" is fixed per site.
4. Package captcha slot: the token response carries `captcha {provider, siteKey}` or null; the hook offers `setCaptchaToken(token|null)` and `captchaRequired`; an expired token means `setCaptchaToken(null)` and a widget reset. The final package is copied only after SLS-Main reports the branch and commit.
5. Server side for ASF is done by SLS Software - CMS (module, captcha) with AndreaSlopFotografie (host); an ASF test host with the endpoint exists only after the CMS branch is merged and deployed (not requested yet).