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:
+40
-3
@@ -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
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user