Events 2.4.0 frontend, deploy and docs: Linked products, linked events, seo

- Site settings → Linked products (Connect, Show events from, Publish my
  events), help, command palette.
- Events from linked products on /events, the home and campus pages, and
  /events/linked/<product>/<id> (markdown with HTML off, canonical to the
  origin, no JSON-LD, not in the sitemap).
- Event page JSON-LD from @crosscode/seo; lib/eventSchema.ts removed.
- Readiness check for linked products' sync; e2e spec with a fake
  Church Website (not run yet: needs the e2e Postgres).
- crosscode: install and build the shared packages Events uses first
  (an older tag still builds as before); scripts/tests/events.bats.
- Release notes, changelogs, handovers, hub-protocol.md, and the plan's
  "Changes while building".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-18 12:58:50 +02:00
co-authored by Claude Opus 5.5
parent 8a930d07c6
commit 716d47242a
28 changed files with 929 additions and 130 deletions
+40 -3
View File
@@ -1,7 +1,10 @@
# Cross Events 2.4.0 — protocol v2, Linked products, the event feed and `packages/seo`
Phase **2** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§4, §5 "Sibling discovery", §9, §11; decisions
5, 20). Written 2026-11-18. **Not started.**
5, 20). Written 2026-11-18. **Built 2026-11-18** on branches (contracts 1.4.0 and Events 2.4.0 on
`feat/events-2.4` here, Hub 2.2.0 on `feat/link-public-key`, crosscode-site on
`feat/linked-products`); not tagged yet. The decisions below were taken as proposed. Where the
build differs from this plan, see [Changes while building](#changes-while-building).
**What 2.4.0 is:** Cross Events becomes a full member of a church stack. It reports to the Hub as
`product: "events"` (protocol v2), shows the church's other products under **Settings → Linked
@@ -35,8 +38,9 @@ sample feeds (§8). It's ready for the Website (phase 4) without another Events
8. [What changes in each repo](#7-what-changes-in-each-repo)
9. [Testing](#8-testing)
10. [Releasing and rolling it out](#9-releasing-and-rolling-it-out)
11. [Decisions](#decisions)
12. [Still open](#still-open)
11. [Changes while building](#changes-while-building)
12. [Decisions](#decisions)
13. [Still open](#still-open)
---
@@ -365,6 +369,39 @@ Order, each with its CHANGELOG entry and `npm run check` first:
4. crosscode-site `v1.4.0`, deployed.
5. Each church updated through the Hub (a scheduled update, ROLLOUT-1.0 §5).
## Changes while building
1. **A different public key never fails the heartbeat** (§1 said `409 PUBLIC_KEY_MISMATCH`): the
heartbeat also refreshes the licence, so failing it could lock a church out after 30 days. The
Hub keeps the saved key, answers `publicKeyStatus: "mismatch"` and opens an alert on the
install; the site keeps sending its key until it gets `saved` or `matches`, so it's saved
right after Joshua clears the old one. Events shows the mismatch on Linked products.
2. **Update requests and AI calls stay on protocol 1** (every Hub accepts them); only register and
heartbeat move to v2. A Hub that refuses a v2 body (`UNSUPPORTED_PROTOCOL` or
`INVALID_REQUEST`) gets the same heartbeat again as v1, and v1 is used for a day. The v2
health fills in what v1 could leave empty (`jobs`, `pendingMigrations`), and the body is
checked against the contract before it's sent.
3. **`event.changed` is tried once more after a minute, then left to the 15-minute poll** (§3
said the webhooks' 1 min … 12 h schedule): retrying longer than the poll interval adds nothing.
4. **The feed is also refreshed before it's served** when the last refresh is over a minute old,
so it's right even with the jobs switched off (e2e, `FEED_JOBS_ENABLED=false`).
5. **Imported events must come from that link's install** (`origin.installId` and `product`),
so one product can't publish events as another. Others are skipped and counted.
6. **JSON-LD**: `organizer` stays an `Organization` (the snapshot rule allowed only additions);
`Church` JSON-LD is in `@crosscode/seo` for the Website. The price range is now from main
tickets only (before, an add-on such as a T-shirt could set the lowest price). The description
goes in as plain text, not the feed's markdown-escaped copy.
7. **The deploy builds the shared packages**: `scripts/products/events.sh` installs and builds
`packages/contracts` and `packages/seo` before Events when the checkout's Events uses them
(an older tag still builds as before; `scripts/tests/events.bats`).
8. **`FEED_JOBS_ENABLED`** (optional, default `true`) switches the `feed` and `feed-sync` jobs,
like the other job flags (in `.env.example` and SETTINGS.md, not the env templates).
9. The readiness check is on the existing readiness page; contracts 1.4.0 also adds
`FEED_PATHS` and `typesVersions` (so `@crosscode/contracts/signing` has types under the
Events backend's `moduleResolution: node`).
10. **Not run yet:** the e2e spec (`e2e/linked-products.spec.ts`, needs the e2e Postgres) and the
VM test (§8): this machine has neither Postgres nor WSL. Both before tagging.
## Decisions
Proposed in this plan, to confirm before building:
+4 -5
View File
@@ -28,7 +28,7 @@ for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released** 2026-11-17 (`events@2.2.0`, with AI use in tokens and the backend under `/api`). **VM tested 2026-11-17** (EVENTS-2.2-PLAN §6, all passing after fixes). **Not rolled out:** servers still run `hope-events` `v2.1.1` until each install is adopted |
| 1c | Cross Events 2.3.x: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). **`events@2.3.1`** 2026-11-18: Next.js 16.4.6 (security advisories for 16.2.0–16.4.4), so roll out 2.3.1, not 2.3.0. crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
| 1d | Agent 1.0.x + Hub 2.1.x (+ contracts 1.3.0) | **Released** 2026-11-17 (`agent@1.0.0`, `contracts@1.3.0`, Hub `v2.1.0`). **VM tested** end to end (AGENT-1.0-PLAN §13: joins, installs behind frp, scheduled / batch / missed updates, uninstall with export and purge, forged and replayed jobs). 2026-11-18: **`agent@1.0.1`** (the agent answers status on the central server itself) and Hub **`v2.1.1`** (adopt passes the church's address; Link takes the short name as a name). **Not rolled out**: use agent 1.0.1 and Hub 2.1.1 |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` (+ contracts 1.4.0, Hub 2.2.0) | **Planned** 2026-11-18: [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md), with six decisions to confirm before building. Events keeps speaking protocol 1 until then |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` (+ contracts 1.4.0, Hub 2.2.0) | **Built** 2026-11-18 ([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md), decisions taken as proposed, "Changes while building" there): `feat/events-2.4` here, `feat/link-public-key` in events-hub, `feat/linked-products` in crosscode-site. Unit tests pass. **Not tagged:** the e2e spec and the VM test haven't run (no Postgres on the dev machine) |
| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
## Next up
@@ -40,10 +40,9 @@ for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
onto the monorepo) → a throwaway New install to prove FASTPANEL, DNS and Let's Encrypt.
2. **Deploy crosscode-site `v1.3.0`** (secure sign-in in the features and the brochure).
3. **Archive `hope-events`** once every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7).
4. **Cross Events 2.4.0** (phase 2): confirm the decisions in
[EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md), then build it in its order (contracts 1.4.0 →
Hub 2.2.0 → Events 2.4.0 → crosscode-site 1.4.0). It can be built during the rollout; releasing
it needs Hub 2.2.0 deployed.
4. **Cross Events 2.4.0** (phase 2) is built on branches: run `npm run test:e2e` in `apps/events`
(with the e2e Postgres) and the VM test in EVENTS-2.4-PLAN §8, then merge and release in its
order (contracts 1.4.0 → Hub 2.2.0, deployed → Events 2.4.0 → crosscode-site 1.4.0).
## The VM test (2026-11-17)
+1 -1
View File
@@ -616,7 +616,7 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
| 1b | **Cross Events 2.2.0** | **Moves into the monorepo** as `apps/events`, with its git history (merged in, not copied); its packages become workspaces; the **`crosscode` script** (`deploy`, `status`, `install`, `adopt`; §8) replaces `scripts/deploy.sh` and `scripts/install.sh`; every install moved with `crosscode adopt`; `hope-events` archived. Planned with no feature changes; two small ones were added on 2026-11-17 (decided by Joshua): **AI use shown in tokens**, never rand, outside the Hub (needs Hub 2.0.1), and **everything the backend serves under `/api`**, so a site and its API share one address and one proxy rule. **Tagged 2026-11-17, before the VM testing; VM tested the same day** | Before more products, so every product is released and deployed the same way from the start |
| 1c | **Cross Events 2.3.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses. **Released 2026-11-17** (`events@2.3.0`) | Independent and useful now; the Accounts migration later carries it over |
| 1d | **Agent 1.0.0 + Hub 2.1.0** (contracts 1.3.0) | **Server agent** on every server (polls only, signed jobs, runs the `crosscode` script); Hub: Servers page with stats and alerts, server configuration, frp port list, New install with a choice of server, scheduled / emergency / batch updates with notice to the church, uninstall with an encrypted JSON export, emailed reports. [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). **Released 2026-11-17** after the VM test; rollout in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) | Right after 1b (it runs the `crosscode` script), so every new church from then on is installed from the Hub. Can run alongside 1c |
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events. **Planned 2026-11-18:** [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md) (also needs contracts 1.4.0 and Hub 2.2.0, for a public key in the v2 heartbeat) | Small; ready for when the Website exists |
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events. **Planned and built 2026-11-18:** [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md) (also needs contracts 1.4.0 and Hub 2.2.0, for a public key in the v2 heartbeat); not tagged yet | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
| 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website |
+21 -3
View File
@@ -332,6 +332,24 @@ what's needed) until the church's install of that product runs that version or l
**AI.** The monthly cap and markup are the church's, shared by all its installs: a call from any of
them counts what all of them used this month.
**Moving an install to v2** (e.g. Cross Events 2.4.0): register again with `protocolVersion: 2`,
the product and a public key (same licence and address: same install id, new secret), then send v2
heartbeats. Nothing on the Hub needs changing.
**Moving an install to v2** (e.g. Cross Events 2.4.0, Hub 2.2.0+): an install that registered with
v1 just starts sending v2 heartbeats, with its Ed25519 public key (PEM) in `publicKey`. It doesn't
need its licence key again (Cross Events never stored it). The heartbeat is already signed with the
install secret, so the Hub knows whose key it is. The reply says what happened in
`publicKeyStatus`:
| `publicKeyStatus` | Meaning |
|-------------------|---------|
| `saved` | The Hub had no key for the install and saved this one; the church's other installs list it from their next heartbeat |
| `matches` | The Hub already has this key (line endings and surrounding whitespace don't count) |
| `mismatch` | The Hub has a **different** key and keeps it: an alert opens on the install, and Joshua can **Clear public key** on its page (two-factor again) when the server was restored or rebuilt; the next heartbeat then saves the new key |
A key problem never fails the heartbeat: the licence keeps refreshing whatever happens to the key.
An install keeps sending `publicKey` until it gets `saved` or `matches`. A Hub before 2.2.0 ignores
the field (no `publicKeyStatus`), so the install isn't listed to its siblings until the Hub is
updated. Registering again with `protocolVersion: 2`, the product and a public key (same licence
and address: same install id, new secret) also works, as before.
**Connecting two installs** (Settings → Linked products → Connect) is between the installs, not
through the Hub: `crosscode.link/1` in `@crosscode/contracts` (`src/link.ts`), with each side
checking the other against the `linkedProducts` it has cached from the Hub.