WIP 2.0.0: React Compiler lint rules back to errors; docs

- The 192 places the rules flagged are fixed and the rules are errors
  again (npx eslint src: nothing). lib/hooks.ts: useStateSync (state
  that follows other state, set while rendering), useExternalEffect
  (API loads and browser reads), useNow; lib/navigation.ts hardNavigate
  for full reloads after sign-out or identity switches; other pages use
  the router. Resets moved into the handlers that cause them.
- The banner shows and hides at its times on open pages.
- HANDOVER, roadmap, README, FEATURES, SETTINGS, CHANGELOG updated;
  2.0.0 section drafted in WHATS-NEW.

e2e 102/102 (PayFast sandbox skipped); production build passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-02 17:45:25 +02:00
co-authored by Claude Opus 5.5
parent 3f59164ab2
commit abd2c36e97
102 changed files with 613 additions and 354 deletions
+75 -34
View File
@@ -1,6 +1,6 @@
# Handover — where things stand and how to carry on
Last updated: 2026-11-02, after **1.52.2** and Hub **1.6.0**; 2.0.0 in progress on `release/2.0`. The plan itself is in
Last updated: 2026-11-02, after **1.52.3** and Hub **1.6.1**; 2.0.0 in progress on `release/2.0`. The plan itself is in
[ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of
features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
@@ -14,6 +14,7 @@ encrypted settings unreadable or break existing installs.
| Version | What |
|---------|------|
| 1.52.3 | **Urgent fix:** licence read-only mode blocks the `/api/v2` routes too (`src/hub/readOnly.js` only listed v1 paths, and the screens have used v2 since 1.51.15). A test checks each blocked v2 path is a real route |
| 1.52.2 | `scripts/deploy.sh` stops first (listing them) when files in the install were changed or added by hand; `--check` runs only that; runs from a copy outside the install too; `ALLOW_LOCAL_CHANGES=1` overrides |
| 1.52.1 | **API documentation complete:** every v2 route documents its body, answer and parameters — the ~300 answered by v1 handlers through `documented` shapes (`src/v2/docs.ts`), shown but not enforced, logged outside production when they don't fit; empty bodies say "No body needed". Test `tests/v2Docs.test.ts` |
| 1.52.0 | **Urgent fix + Corrections:** required attendee forms no longer leave paid door/manual registrations without tickets — popup with "Fill in later" (`Registration.formWaivedAt`, `POST /api/v2/registrations/{id}/form-later`); one form per person on picked sessions; forms with no questions don't hold tickets; kiosk asks for the forms the server says are missing. Admin **Corrections** page (`src/services/corrections.ts`, `/api/v2/corrections/…`): issue missing tickets, pay later (`ticketsReleasedAt`), make it free (`complimentaryDiscount`), check in after the event. Migration `20261102120000_corrections`. e2e `e2e/corrections.spec.ts` |
@@ -79,40 +80,35 @@ encrypted settings unreadable or break existing installs.
## Next up
Hub 1.1.0 is deployed with update requests rolled out, and `scripts/install.sh` has been tried on
a test server (both done 2026-10-28).
1. **2.0.0 — in progress on `release/2.0`** (WIP commit per part; tag 2.0.0 only when all of it
is in). The parts and their state are in the roadmap's Status table:
- ✅ **Hub 1.6.0** — the AI proxy (tagged, pushed). Real Claude calls tested 2026-10-30 through
a local Hub with Joshua's key: fine, and a fraction of a cent each.
- ✅ **AI plumbing** on Cross Events (`backend/src/ai/`, `/api/v2/ai/*`, Site settings → AI,
`<AiButton>`, `useAiStatus()`; roadmap §15 "Progress").
- **Next: the five helpers** (`backend/src/ai/helpers.ts`, their routes and buttons, an eval set,
privacy notice text).
- Then **v1 removed** — keep answering the v1 webhook paths and the old links in sent messages
(`src/v2/links.ts`): providers and old emails still use them. Then the **migration guide**.
1. **2.0.0 — on `release/2.0`** (a WIP commit per part; tag 2.0.0 only when all of it is in).
State per part is in the roadmap's Status table:
- ✅ **Hub 1.6.0 – 1.6.1** — the AI proxy, model list with prices (Sonnet 5.5 for every helper).
- ✅ **AI plumbing** and ✅ **the five helpers** with their buttons, the eval set (`npm run ai:eval`,
19/19 through a local Hub on 2026-10-30) and the privacy notice text.
- ✅ **v1 removed** (2026-11-02, see [v1 removed](#v1-removed-20)), with ✅ **Argon2id passwords**
([Passwords](#passwords-20)) and ✅ `node-fetch` gone. Backend 690 tests and e2e 102/102 pass.
- ✅ **Migration guide:** `MIGRATING-TO-2.md` (generated v1 → v2 table at the end).
- ✅ **React Compiler lint rules back to errors** (2026-11-02; see [Next.js 16](#nextjs-16-1515)) —
`npx eslint src` clean, e2e 102/102, production build passes.
- **Still to do for 2.0:** the 2.0.0 sections of WHATS-NEW.md (church-facing: AI helpers,
stronger passwords; nothing else they'd notice) and the CHANGELOG heading; README/FEATURES/
SETTINGS passes for v1 references (README still lists `/api/...` endpoints); then merge
`release/2.0` into `main` and tag `v2.0.0`.
- **Marketing site** (roadmap §17): a simple static HTML site — Cross Code as the main site,
with a Cross Events page; room for a church app and a full church website later. Repo,
domain and hosting to decide first.
with a Cross Events page. Repo, domain, hosting, prices shown or not, and the contact route
to decide first.
- Testing AI locally: run the Hub (`../events-hub`, port 5200), set Settings → AI there, give a
test licence an AI cap, and start Cross Events with `HUB_URL=http://localhost:5200`.
2. **AI rules** (decided 2026-10-29, roadmap §15): the AI buttons show only when the licence's
monthly cap is above R0, and are disabled (not hidden) once it's reached. The Hub charges the
real cost plus a markup % (a default and a per-licence override) and counts the cap in charged
rand. AI endpoints are `/api/v2` only. The model is **Claude Sonnet 5.5** for every helper
(2026-10-30, after a Haiku/Sonnet trial), set on the Hub (Settings → AI, Hub 1.6.1); its list
rand. AI endpoints are `/api/v2` only. The model is set on the Hub (Settings → AI); its list
prices live in `events-hub/backend/src/utils/aiModels.js`.
3. **Clean-ups before or with 2.0:**
- Turn the React Compiler lint rules back to errors (see [Next.js 16](#nextjs-16-1515)) — every
screen is on v2 now, but they're still `warn` in `frontend/eslint.config.mjs`.
- `node-fetch` is still listed in `backend/package.json` though nothing in `src/` uses it —
remove it.
- Password hashing upgrade with rehash-on-login (roadmap §14) isn't done: still `bcryptjs`.
Decide whether it's in 2.0.
4. **Later:** move from ExcelTS — deprecated in favour of `documonster` by the same author
(pre-1.0 in Oct 2026) — once documonster is stable. After 1.51.7 has run everywhere, the old
`pgboss` schema can be dropped (`DROP SCHEMA pgboss CASCADE;`).
3. **Later (2.x):** move the v1 controllers behind `v1Route` into TypeScript services (the v2 API
doesn't change); remove the handlers no v2 route uses any more (e.g. the v1 scan handler and
`v1ScanResponse`, `v1Status` in `services/errors.ts`). Move from ExcelTS to `documonster` once
it is stable. After 1.51.7 has run everywhere, drop the old `pgboss` schema
(`DROP SCHEMA pgboss CASCADE;`).
Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026-10-28).
@@ -129,8 +125,8 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026
- **Changelog:** add entries to `[Unreleased]` as you go, in plain language. CHANGELOG.md is the
full log; WHATS-NEW.md is what churches see before updating (the Hub reads it from main every
15 minutes, for tagged versions only and sets the latest version from the tags — nothing to do in the Hub).
- **Docs to keep in step:** CHANGELOG.md, FEATURES.md, README.md, SETTINGS.md,
backend/API_DOCUMENTATION.md, the `/docs` route list in `backend/src/app.js` (v2 documents itself), and
- **Docs to keep in step:** CHANGELOG.md, FEATURES.md, README.md, SETTINGS.md (the API documents
itself at `/docs/v2`; `backend/API_DOCUMENTATION.md` only points there), and
in-app help in `frontend/src/content/help/` (register new pages in `registry.ts`).
- **Prisma migrations:** `npx prisma migrate dev --create-only --name x` against a local
DB. Prisma 7 keeps adding an unrelated `_EventNotifyRecipients` primary-key/index
@@ -585,10 +581,27 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026
- Turbopack for dev and build (the default). Lint with `npm run lint` / `npx eslint src` (`next lint`
is gone). There's no middleware/proxy file — add `src/proxy.ts` (Next 16's name) only if needed.
- **React Compiler lint rules are warnings, not errors** (`eslint.config.mjs`): 181 existing places,
mostly `useEffect(() => { load(); }, [...])`. The plan was to fix them as each screen moved onto
v2; every screen is on v2 now (1.51.15) but the rules are still `warn` — fix what's left and turn
them back to errors before or with 2.0. Don't add new ones.
- **React Compiler lint rules are errors** again (2.0; they were warnings from 1.51.5 with 181
places to fix). How the code meets them — `frontend/src/lib/hooks.ts`:
- **State that follows other state or props** ("when the event changes, start the form again",
"each time the popup opens, clear it"): `useStateSync(update, deps)` — updates while rendering
(React's "adjusting state when a prop changes"). Deps must be stable values: a new array or
object each render loops (e.g. key on `campuses[0]?.id`, not the list). Prefer computing in
render, or setting it in the event handler that causes the change.
- **Loading from the API or reading the browser** (localStorage, the URL, a cookie, browser
events) and setting state from it: `useExternalEffect(run, deps)` — `useEffect` under a name that
says why. Both hooks' deps are checked by exhaustive-deps (`additionalHooks` in
`eslint.config.mjs`); to reload when something not used in the body changes, name it inside
(`void user;`).
- **Search results that clear when the box is emptied:** don't clear them in the effect — show
`query ? results : []` and let the effect only set state when the answer comes.
- **Time:** `useNow()` in client components (re-renders every minute); server components may
call `Date.now()` with the disable comment that says why (one render per request).
- **Navigation:** `useRouter().push()`; `hardNavigate()` (`lib/navigation.ts`) only where the
whole app must start again (signing out, impersonation, the 2FA redirect in `lib/api.ts`);
`window.location.assign(url)` for payment providers.
- The one deliberate exception is `useAnchorRect` (events page): measuring the DOM in
`useLayoutEffect` before paint.
- `eslint-config-next` 16's bundled plugins (react, import, jsx-a11y) don't list ESLint 10 as a peer
yet; they work, and npm notes the override. Revisit when they publish ESLint 10 support.
@@ -645,6 +658,34 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026
`utils/webhooks.js`; `tests/webhooks.test.js` fails if an example and `buildPayload` differ in
shape.
## v1 removed (2.0)
- `/api/…` answers **410** `API_V1_REMOVED` (`v1Removed` in `src/v2/links.ts`), except what outside
senders still use: `/api/webhooks/yoco|payfast|whatsapp` (`routes/webhookRoutes.js`, before the
JSON parser), WAWP's oldest `/api/whatsapp/webhook` and a mail app's one-click POST to
`/api/privacy/unsubscribe/:token/one-click` (`legacyV1Router`), and the 308s for links in sent
messages (`legacyLinkRedirects`). `/docs` redirects to `/docs/v2`.
- Only three v1 route files are left: `webhookRoutes.js`, and `dashboardRoutes.js` /
`savedFilterRoutes.js`, whose handlers v2 runs as routers. The controllers stay — `v1Route` runs
them behind v2 routes.
- **Path lists name v2 paths:** `hub/readOnly.js` (add any new "create" route there, with a test in
`tests/hub.test.js`, which also checks each pattern is a real route), `ALLOWED_WRITES` in
`utils/impersonation.js`.
- **Campus scope test** is `tests/v2CampusScope.test.ts`: every staff/supervisor v2 route has a
marked middleware (`scopeEvent`, `scopeBody`, `scopeList`, `campusIndependent`…) or is listed in
`CHECKED_IN_HANDLER` because its service checks campuses itself.
- e2e calls v2 only: `v2(page, role, method, url, body)` in `e2e/fixtures.ts` returns `data`.
Playwright waits for `/api/v2/setup/needed`.
## Passwords (2.0)
- `src/config/auth.js`: `hashPassword` is Argon2id (`@node-rs/argon2`, 19 MiB, 2 passes, 1 lane —
OWASP's minimum; prebuilt binaries, nothing to compile). `comparePassword` checks Argon2 and the
bcrypt hashes from before 2.0 (`bcryptjs` stays for that). `needsRehash` is true for bcrypt or
weaker Argon2 settings; `logIn` (`services/auth.ts`) saves a new hash after a right password.
- Raising the settings later: change `ARGON2` — everyone is re-hashed at their next sign-in.
Tests: `tests/passwords.test.js`, and the re-hash in `tests/accountEnumeration.test.ts`.
## Known gaps / follow-ups
- WhatsApp STOP only works once someone pastes the webhook URL from Site settings → WhatsApp
+2 -2
View File
@@ -20,8 +20,8 @@ when all of it is in (decided 2026-10-30):
| 1 | AI proxy: key, metering in rand, caps, markup, usage views; model list with prices (Sonnet 5.5 default) | Hub 1.6.0 – 1.6.1 (`events-hub`) | ✅ tagged; real Claude calls tested 2026-10-30 |
| 2 | AI plumbing: `/api/v2/ai/status`, usage, Site settings → AI, `<AiButton>`, `useAiStatus()`, `AiCall` log, Anthropic operator entry | `release/2.0` | ✅ committed (WIP) |
| 3 | The five helpers (§15) with their buttons, an eval set, privacy notice text | `release/2.0` | ✅ committed (WIP); eval 19/19 through a local Hub (2026-10-30) |
| 4 | v1 removed (webhook paths and old message links keep working); clean-ups: Argon2id passwords with rehash-on-login, `node-fetch` gone, React Compiler lint rules back to errors | `release/2.0` | ✅ v1, passwords, `node-fetch` (2026-11-02); lint rules in progress |
| 5 | Migration guide (`MIGRATING-TO-2.md`), docs | `release/2.0` | guide ✅ (2026-11-02); docs in progress |
| 4 | v1 removed (webhook paths and old message links keep working); clean-ups: Argon2id passwords with rehash-on-login, `node-fetch` gone, React Compiler lint rules back to errors | `release/2.0` | ✅ (2026-11-02) |
| 5 | Migration guide (`MIGRATING-TO-2.md`), docs | `release/2.0` | ✅ guide and docs (2026-11-02); 2.0.0 WHATS-NEW drafted |
| 6 | Marketing site: Cross Code with a Cross Events page (§17) | its own repo | to do — repo, domain, hosting, prices and contact route still to decide |
The full version list is in [HANDOVER.md](./HANDOVER.md) and the [build order](#suggested-build-order) below.