diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index ee26a3b..8a83d62 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -1,14 +1,16 @@ # Handover — where things stand and how to carry on -Last updated: 2026-11-17, after **2.3.0** (released, tested on a VM, not deployed yet; servers -still run 2.1.1 until they're adopted, see the root [ROLLOUT-1.0.md](../../../docs/ROLLOUT-1.0.md)). +Last updated: 2026-11-18, after **2.3.1** (Next.js 16.4.6 for security advisories, on top of 2.3.0; +released, not deployed yet; servers still run 2.1.1 until they're adopted, see the root +[ROLLOUT-1.0.md](../../../docs/ROLLOUT-1.0.md)). **This file covers Cross Events only** (what's been done, where the code lives, known gaps). **The plan for every product and where each phase stands are in the monorepo's root `docs/`** → [ROADMAP-v3.md](../../../docs/ROADMAP-v3.md), [HANDOVER.md](../../../docs/HANDOVER.md) (all products) and -[EVENTS-2.2-PLAN.md](../../../docs/EVENTS-2.2-PLAN.md) (the next Events release: -the move into the monorepo). The Hub protocol is there too ([hub-protocol.md](../../../docs/hub-protocol.md)). How Cross +[EVENTS-2.4-PLAN.md](../../../docs/EVENTS-2.4-PLAN.md) (the next Events release: protocol v2, +Linked products, the event feed and `packages/seo`; the move into the monorepo was +[EVENTS-2.2-PLAN.md](../../../docs/EVENTS-2.2-PLAN.md)). The Hub protocol is there too ([hub-protocol.md](../../../docs/hub-protocol.md)). How Cross Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round before that in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md). @@ -98,9 +100,10 @@ encrypted settings unreadable or break existing installs. 1. **Roadmap v3**, across every product: see `crosscode-platform/docs/HANDOVER.md` ("Where each phase stands", "Next up"). **2.2.0** (the move into the monorepo) and **2.3.0** (authenticator - app 2FA and recovery codes, plus what installs from the Hub need) are released (2026-11-17). - Next for Cross Events is **rolling them out** (each install adopted from the Hub), then **2.4.0** - (protocol v2, Linked products, the event feed). + app 2FA and recovery codes, plus what installs from the Hub need) are released (2026-11-17; + **2.3.1** with Next.js 16.4.6 on 2026-11-18). Next for Cross Events is **rolling them out** + (each install adopted from the Hub, on 2.3.1), then **2.4.0** (protocol v2, Linked products, + the event feed), planned in [EVENTS-2.4-PLAN.md](../../../docs/EVENTS-2.4-PLAN.md). - **Deploying:** installs still on 2.1.1 move with `adopt` (Hub → Servers → Installs → Link existing → Move onto the monorepo, or `crosscode adopt` by hand), never `deploy`. After that, updates are planned on the Hub (Updates), or `crosscode deploy events` by hand. diff --git a/docs/EVENTS-2.4-PLAN.md b/docs/EVENTS-2.4-PLAN.md new file mode 100644 index 0000000..d637c0c --- /dev/null +++ b/docs/EVENTS-2.4-PLAN.md @@ -0,0 +1,392 @@ +# 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.** + +**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 +products** with a **Connect** button, **publishes** its public events as a `crosscode.event-feed/1` +feed, **shows** events from linked products, and builds its SEO data with the new shared +`packages/seo`. Nothing changes for a church that has only Cross Events, apart from a new +settings page that says "No other products yet". + +The Website and App don't exist yet, so the "show events from" side is built and tested against +sample feeds (§8). It's ready for the Website (phase 4) without another Events release. + +**Done when:** + +- `events@2.4.0`, `contracts@1.4.0` and Hub `v2.2.0` are tagged and pushed. +- An Events install updated to 2.4.0 moves itself to protocol v2 with no admin action, and the + Hub shows it as v2 with a public key. +- The feed passes the contract (`parseEventFeed` with nothing rejected) for every event in the + e2e seed, and a sample Website feed shows up in Events with a canonical link to its origin. +- crosscode-site says "Works with the Church Website and App (coming)" on the Cross Events page + (ROADMAP §9, "Updating crosscode-site"). + +## Contents + +1. [Before starting](#before-starting) +2. [Protocol v2](#1-protocol-v2) +3. [Linked products and Connect](#2-linked-products-and-connect) +4. [Publishing: the feed](#3-publishing-the-feed) +5. [Showing events from linked products](#4-showing-events-from-linked-products) +6. [`packages/seo`](#5-packagesseo) +7. [Settings, audit log and help](#6-settings-audit-log-and-help) +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) + +--- + +## Before starting + +- **The rollout (ROLLOUT-1.0.md) is at least past step 1**, so production runs Hub 2.1.x. 2.4.0 + needs Hub 2.2.0 (§1) and is released after it, but neither depends on the church servers + being adopted. +- `apps/events` builds and tests clean on `main` (`npm run check`), as the baseline. +- Events uses `@crosscode/contracts` as a workspace dependency for the first time (backend and + frontend). The backend is CommonJS with some TypeScript; the package ships both builds, so + `require('@crosscode/contracts')` works as it is. + +## 1. Protocol v2 + +Today `src/hub/client.js` speaks protocol 1 (`PROTOCOL_VERSION = 1`). v2 is in +`@crosscode/contracts` (`hub.*`) and the Hub has accepted it since 2.0.0 +([hub-protocol.md §6](./hub-protocol.md#6-protocol-version-2-hub-20)). + +**The problem:** hub-protocol.md says an install moves to v2 by *registering again* with its +licence key and a public key. Events never stored the licence key (it's only sent once, from +`/setup` or "Connect to Hub"), so every church admin would have to find and retype it. The v2 +heartbeat also has no way to send a public key. + +**The fix (Hub 2.2.0, contracts 1.4.0):** the v2 heartbeat gets an optional `publicKey` (PEM). +The heartbeat is already signed with the install secret, so the Hub knows it's that install. The +Hub saves the key when the install has none, and refuses a *different* key +(`409 PUBLIC_KEY_MISMATCH`) unless Joshua clears it on the install's page (for a restored server +that lost its key). An optional field keeps the protocol at version 2 and the contract at `/1` +(ROADMAP §2, "Versioning"). + +What Events does: + +| Step | Detail | +|------|--------| +| Key pair | On first start of 2.4.0, generate an Ed25519 key pair (`generateEd25519` from `@crosscode/contracts/signing`). Private key encrypted in `AppSetting` `hub_private_key` (same `encrypt` as the install secret), public key in `hub_public_key`. Both added to `HUB_KEYS`, so the generic settings endpoints never show them. Never regenerated unless missing | +| Heartbeat | `protocolVersion: 2`, `product: "events"`, `publicKey` until the Hub has acknowledged it (`hub_public_key_ack`), Events stats as in v1. Body checked with `hub.heartbeatRequestSchema` before sending (a bug shows in tests, not as a 400 in production) | +| Register | `/setup` and "Connect to Hub" register with v2 straight away (`product`, `install.publicKey`) | +| Reply | Reads `linkedProducts` (§2) and the licence's `customerId` / `product`; everything else as v1 | +| Falling back | If the Hub answers `400 UNSUPPORTED_PROTOCOL` (a Hub older than 2.0), send v1 and keep trying v2 once a day. Not expected in production; it keeps a restored old Hub from cutting installs off | + +`hub-protocol.md` §6 "Moving an install to v2" is rewritten to describe this (both copies). + +## 2. Linked products and Connect + +**Settings → Linked products** (site admins only) lists the church's other installs from the +last heartbeat's `linkedProducts` (cached in `AppSetting` `hub_linked_products`, so a Hub outage +changes nothing; ROADMAP §5). For each: product name, address, and its state: **Not connected** +· **Connected** (since when, by whom) · **Connected, last sync failed** (when, why). + +With Events only, the page says the church has no other Cross Code products yet, with a link to +crosscode.co.za. + +### Connect + +The Hub tells each install which siblings exist and their public keys. **Connect** turns that +into a working link: a shared secret for signed calls between the two, and the feed settings. +New contract: **`crosscode.link/1`** in `packages/contracts/src/link.ts`. + +``` +A (Events) B (e.g. Website) + admin clicks Connect + makes a 32-byte secret S + POST {B.url}/api/links/v1/connect ───────────────► 1. A is in B's own cached linkedProducts + { (same Hub customer), by installId + schema: "crosscode.link/1", 2. the Ed25519 signature checks out against + type: "link.connect", the publicKey the Hub listed for A + from: { product, installId, url }, 3. `to.installId` is B; issuedAt within + to: { installId }, 5 minutes; nonce not seen before + secret: S, 4. stores S (encrypted), marks A connected + issuedAt, nonce, ◄── 200 { schema, type: "link.connected", + signature: from: {…B}, publicKey check, signature } + } + checks B's signed reply with B's Hub-listed key + stores S (encrypted), marks B connected +``` + +- **Trust comes from the Hub's list on both sides.** B accepts A only if A appears in *B's* + `linkedProducts` with that exact key, so only installs of the same church can link, and only + ones the Hub knows. The Hub is still not on the path at the time of the call (rule 2): both + sides use their cached lists. +- **No approval step on B.** Both installs belong to the same church; whoever is admin on either + side can connect. B's Linked products page shows "Connected by Cross Events on 18 Nov" and + either side can **Disconnect** (a signed `link.disconnect`; both drop the secret). +- **Connecting again** replaces the secret (e.g. after a restored backup lost it). +- After Connect, every call between the two (the `event.changed` webhook now, Accounts' + back-channel later) uses `LINK_HEADERS` HMAC with S, as `@crosscode/contracts/signing` already + defines. +- Errors are `crosscode.link/1` `{ message, code }`: `NOT_LINKED` (A isn't in B's list: "Wait for + the next Hub heartbeat, up to 15 minutes, or check the Hub"), `BAD_SIGNATURE`, `STALE_REQUEST`, + `REPLAYED`, `WRONG_INSTALL`. +- Key format: the Hub lists keys as PEM, while the agent helpers in `signing.ts` take raw + base64url. contracts 1.4.0 adds `ed25519PublicFromPem` / `signLink` / `verifyLink` so no + product converts by hand. +- Events also **answers** Connect, since a Website will usually be the one clicking it. + `POST /api/links/v1/connect` and `/disconnect` are public routes, rate-limited per IP, outside + `/api/v2` (they're a cross-product contract, like the feed). + +Stored per link in a new table, not in `AppSetting`: + +```prisma +model ProductLink { + installId String @id // the sibling's Hub install id + product String // website | app | accounts + url String + publicKey String // as listed by the Hub when connected + secret String // encrypted + connectedAt DateTime + connectedBy String? // a user id when connected here, null when the sibling did it + showEvents Boolean @default(false) // "Show events from" (§4) + lastSyncAt DateTime? + lastSyncError String? + lastGoodAt DateTime? +} +``` + +If a sibling disappears from `linkedProducts` (uninstalled, or the licence moved), the link stays +but shows **No longer listed by the Hub**. Its events keep showing until an admin removes the +link, so a Hub mistake can't empty the church's event list. + +## 3. Publishing: the feed + +`GET /api/feed/v1/events?updatedSince=` → `crosscode.event-feed/1` (ROADMAP §4, +"Transport"). Public, no sign-in: it only carries what the public event pages already show. It +answers only when **Publish my events** is on (default **on**; otherwise `404 FEED_OFF`). + +### Which events + +The same rule as the public pages, `publicEventWhere()` in `src/utils/series.js`: `isActive`, not +`isHidden`, `goLiveAt` passed. Plus: + +- Events that ended more than **30 days** ago are left out of a full fetch (no `updatedSince`). + An event that ends doesn't go into `deleted`: siblings keep their copy and drop it from + "upcoming" themselves. +- An event's campus goes out as `campus: { slug, name }`, `null` for all campuses. +- **Never** in the feed: kids check-in and volunteer options, contact name/phone/email (the + church's contact for an event can be a person), the attendee form, prices of staff-only options. + +### `updatedAt` and `deleted` that are actually right + +An event's public face changes without its row changing: it goes live when `goLiveAt` passes, +registration closes at the deadline, and it fills up as tickets sell. `Event.updatedAt` misses +all three, and Events never deletes an event (`deleteEvent` deactivates it). So the feed is kept +in a table of what was last published: + +```prisma +model FeedEntry { + eventId String @id + hash String // sha256 of the canonical crosscode.event/1 payload + payload Json + changedAt DateTime // the event's `updatedAt` in the feed + removedAt DateTime? // set when it stops being public: goes into `deleted` +} +``` + +- A **`feed-refresh`** job (pg-boss, every 5 minutes, and queued straight after an event, option, + session or registration change through the existing Prisma extension in `config/db.js`) builds + each candidate event's `crosscode.event/1`, compares the hash and bumps `changedAt` only when + something a sibling would see has changed. An event that stopped being public gets `removedAt`. +- The feed answers from this table: `events` = rows with `changedAt > updatedSince` and no + `removedAt`; `deleted` = rows with `removedAt > updatedSince`. With no `updatedSince`, every row + without `removedAt`. Rows removed more than 90 days ago are cleaned up. +- When the job changes anything, it sends **`event.changed`** (`eventChangedSchema`, at most 100 + ids) to every connected link, signed with that link's secret, using the retries and SSRF rules + of `utils/webhooks.js` (1 min, 5 min, 30 min, 2 h, then give up; the 15-minute poll catches up). + +### Building `crosscode.event/1` from an Event + +A new `src/feed/toCrosscodeEvent.ts`, checked against `eventSchema` in tests for every e2e seed +event: + +| Field | From | +|-------|------| +| `id` | `Event.id` (already a UUID) | +| `origin` | `{ product: "events", installId: hub_install_id, url: /events/ }` | +| `status` | `published` (Events has no "cancelled" state today: cancelling is deactivating, so it goes into `deleted`) | +| `summary` | `null` (no such field yet) | +| `description` | The plain-text description with markdown characters escaped, so it reads the same when rendered as markdown | +| `imageUrl` | `picture`, made absolute | +| `timezone` | The site timezone (`TIMEZONE`) | +| `startsAt` / `endsAt` / `allDay` / `sessions` | `utils/sessions.js` (already keeps start/end in step with the sessions); `allDay: false` | +| `location` | `{ name: location, address: null, onlineUrl: null }`, or `null` | +| `series` | `{ id, name }` | +| `tags` | `[]` (no tags in Events yet) | +| `registration` | `mode`: `origin` when `requiresRegistration`, else `contact`; `url` the event page; `status` from the same rules as the event page (`not_open` before go-live, `closed` after the deadline or late-join cut-off, `full` when every limited main option is sold out, `waitlist` when full with a waitlist); `priceFrom` = the lowest current public price (early-bird and variants as in `eventSchema.ts` today), `null` when free | + +## 4. Showing events from linked products + +Per connected link: **Show events from this product** (off by default; ROADMAP §4 "Show events +from"). When on: + +- **Sync:** a `feed-sync` job per link every **15 minutes**, and straight away on a valid + `event.changed` (`POST /api/feed/v1/changed`, verified with `LINK_HEADERS` and that link's + secret). It fetches `?updatedSince=`, 15 s timeout, parses with + `parseEventFeed` (rejected events are logged, never block the rest), and upserts into + `ImportedEvent`. One failing link never holds up another (separate jobs). +- **The last good copy stays.** A failed sync only sets `lastSyncError`; admins see "Last synced + 2 hours ago" on Linked products and on the dashboard's event list. +- **Read-only**, keyed by `origin.product` + `id` (`eventKey`), and **never re-published**: the + feed only ever reads `Event`, so no loops (ROADMAP §4 rules). +- Turning **Show events from** off, or removing the link, deletes that link's imported events. + +```prisma +model ImportedEvent { + key String @id // eventKey(): ":" + linkId String // ProductLink.installId + payload Json // the crosscode.event/1 as received + startsAt DateTime // copied out for sorting and "upcoming" + endsAt DateTime + campusSlug String? + updatedAt DateTime + @@index([linkId]) + @@index([startsAt]) +} +``` + +**Where they show:** on the public **Events** list, the home page's upcoming events and campus +pages (by `campus.slug`, when it matches one of Events' campuses; otherwise under all campuses), +mixed in by date, with a small "From the church website" label. Not in the dashboard's event +tools, reports, check-in or anything that registers people. + +**Their page:** `/events/linked//`: title, dates, sessions, place, image, the +description rendered as markdown with HTML off (`react-markdown`, new dependency), and one button +by `registration.mode`: **More details** / **Register** linking to the origin (`origin` / +`external`), or the contact instructions (`contact`). The page has +`` to `origin.url` (ROADMAP §11, "Imported events"), is left out of +`sitemap.xml`, and has no `Event` JSON-LD (the origin's page carries it, so search engines see +one event). + +## 5. `packages/seo` + +A new workspace, `@crosscode/seo` (ROADMAP §11): the schema.org builders and meta helpers every +product will use, built on `@crosscode/contracts`. Pure functions, no framework, ESM + CJS like +contracts, its own Jest tests. + +| Export | What | +|--------|------| +| `eventJsonLd(event: CrosscodeEvent, opts)` | `Event` JSON-LD from `crosscode.event/1`: `eventStatus` (`EventCancelled` for `cancelled`), attendance mode (`OnlineEventAttendanceMode` / `Mixed…` from `location.onlineUrl`), `Place` or `VirtualLocation`, `offers` from `registration` (`SoldOut` for `full`, `validFrom` from `opensAt`), sessions as `subEvent` | +| `churchJsonLd(church: Church)` | `Church` (a schema.org `Organization` subtype): name, logo, address, geo, phone, service times as `openingHoursSpecification`-style `Event` entries, `sameAs` social links. Used for the Website's home page later; Events uses it as the event `organizer` | +| `canonicalUrl(base, path)` | Drops tracking parameters (`src`, `utm_*`, `fbclid`, `gclid`) and the trailing slash rule in one place | +| `pageMeta({ title, description, … })` | Title length and description trimming rules (60 / 155 characters), used for the Website's warnings later | + +**Events moves onto it:** `frontend/src/lib/eventSchema.ts` is replaced. The public event detail +answer gains `crosscodeEvent` (the same builder as the feed, §3), and the page calls +`eventJsonLd` with it. **Nothing gets worse for Google:** today's JSON-LD gives a price *range* +(`AggregateOffer` low–high); `crosscode.event/1` only has `priceFrom`. `eventJsonLd` takes an +optional `priceRange` for the origin's own page, so Events keeps sending the high price. A +snapshot test compares the old and new JSON-LD for each seed event; the only allowed +differences are additions (`subEvent`, `organizer` as a `Church`). + +The `organizer` comes from a `crosscode.church/1` that Events builds from its own site settings +(name, logo, colours, contact email). Sharing that profile with siblings is not part of 2.4.0 +(see [Still open](#still-open)). + +## 6. Settings, audit log and help + +- **Settings → Linked products** (new page): the list, Connect / Disconnect, **Show events + from**, last sync. **Settings → Site → Publish my events** (on by default) with one line on + what it shares ("Your public events, as they appear on your events page. Never anyone's + details."). +- **Audit log** (`utils/adminAudit.js`): `product_link_connected`, `product_link_disconnected`, + `feed_publish_toggled`, `feed_show_toggled`. Connections made by the sibling are logged with + no user. +- **Help:** a "Linked products" help article, and the setting descriptions. **What's new** for + 2.4.0: "Ready for the Church Website and App: your events can show on them, and theirs here. + Nothing changes until you have them." +- **Readiness checks** (`utils/readiness.js`): warn when a link's last sync failed for more than + a day. + +## 7. What changes in each repo + +| Repo | Change | Version | +|------|--------|---------| +| `crosscode-platform` `packages/contracts` | `crosscode.link/1` (`link.ts`: connect, connected, disconnect, errors), optional `publicKey` on the v2 heartbeat, `ed25519PublicFromPem` / `signLink` / `verifyLink`, JSON Schema and samples for each | `contracts@1.4.0` | +| `crosscode-platform` `packages/seo` | New (§5) | Not tagged on its own: a workspace, versioned with its first user like `ui` | +| `crosscode-platform` `apps/events` | §1–§6. Migrations: `ProductLink`, `FeedEntry`, `ImportedEvent`. New deps: `@crosscode/contracts`, `@crosscode/seo` (workspace), `react-markdown` | `events@2.4.0` | +| `crosscode-platform` `docs/` | `hub-protocol.md` §6 (heartbeat `publicKey`, moving to v2), ROADMAP §9 phase 2 marked done, HANDOVER | — | +| `events-hub` | v2 heartbeat accepts and saves `publicKey` (`409 PUBLIC_KEY_MISMATCH` for a different one), **Clear public key** button on the install page (2FA again, audited), vendored `contracts-1.4.0.tgz`, its copy of `hub-protocol.md` | Hub `v2.2.0` | +| `crosscode-site` | "Works with the Church Website and App" on the Cross Events page, marked coming (`src/data/cross-events.mjs`) | `v1.4.0` | + +New `.env` variables: **none planned.** If one turns up, it goes in all three templates +(HANDOVER, "Things to remember"). + +## 8. Testing + +**Unit and integration (Jest, in `npm run check`):** + +- contracts: `crosscode.link/1` samples parse; `signLink` / `verifyLink` refuse a changed body, + another key, a stale `issuedAt` and a replayed nonce. +- seo: `eventJsonLd` / `churchJsonLd` for every contract sample; the old-vs-new snapshot (§5). +- Events, Hub client: the v2 heartbeat body passes `hub.heartbeatRequestSchema`; the key pair is + made once; `publicKey` stops being sent after the ack; falling back to v1 on + `UNSUPPORTED_PROTOCOL`. +- Events, feed: every e2e seed event passes `eventSchema`; hidden, inactive, not-yet-live and + kids/volunteer data never appear; `updatedSince` returns exactly what changed, including + go-live, deadline and selling out with no `Event` row change; deactivating puts it in + `deleted`; feed off → `404 FEED_OFF`. +- Events, Connect: accepted from a listed sibling; refused when not listed, with a key other + than the listed one, stale, replayed or for another install; disconnect from either side. +- Events, sync: a sample Website feed with one invalid event (the rest import, the bad one is + logged); the source down (last copy kept, error shown); `event.changed` with a bad signature + refused; imported events never in our own feed. +- Hub (`events-hub`): v2 heartbeat with a key saves it; the same key is fine; a different one is + `409`; Clear lets a new one in. + +**e2e (Playwright, `apps/events/e2e`):** a small fake "Website" (a fixture server in the e2e +setup serving `samples/event-feed.json` and answering Connect) to click through Linked products +→ Connect → Show events from → the imported event on `/events` → its page with the canonical link +and the origin's button; `sitemap.xml` doesn't list it. The §11 checks (title, description, +canonical, `og:image`, one `

`, JSON-LD parses) on the event page and the imported event page. + +**On the VM** (as in AGENT-1.0-PLAN §13), before tagging: two installs of Events can't be linked +(one per product per customer), so the VM run uses the fake Website from e2e as a second site +behind frp, against Hub 2.2.0. Check: an existing 2.3.x install updated through the agent moves +itself to v2 and appears with a key on the Hub; Connect works across the two servers; turning +the fake Website off keeps its events showing with "last synced". + +## 9. Releasing and rolling it out + +Order, each with its CHANGELOG entry and `npm run check` first: + +1. `contracts@1.4.0` (platform), then the packed `.tgz` into `events-hub/backend/vendor/`. +2. Hub `v2.2.0`, deployed (`events-hub/deployment.md`). +3. `events@2.4.0` (its `WHATS-NEW.md` heading needs no `requires`: against a Hub before 2.2.0 it + still works, only Linked products stays empty). +4. crosscode-site `v1.4.0`, deployed. +5. Each church updated through the Hub (a scheduled update, ROLLOUT-1.0 §5). + +## Decisions + +Proposed in this plan, to confirm before building: + +1. **Moving to v2 needs no admin action:** the v2 heartbeat carries the install's public key + (optional field), instead of re-registering with the licence key (§1). Needs Hub 2.2.0. +2. **Connect needs no approval on the other side**, and trust comes from each side's own cached + Hub list (§2). +3. **Publish my events is on by default** (it only shares what the public pages already show); + **Show events from** is off by default per link. +4. **The feed is built from a `FeedEntry` table**, not straight from `Event`, so go-live, + deadlines and selling out are reported as changes (§3). +5. **Imported events get their own page** in Events with a canonical link to the origin, rather + than linking straight out from the list (§4). +6. Ended events stay out of `deleted`; a full fetch covers events that ended up to 30 days ago. + +## Still open + +- **Who owns the church profile (`crosscode.church/1`)** once there's more than one product? + Events builds one from its own settings for its JSON-LD in 2.4.0, but doesn't serve it to + siblings. The Website (phase 4) is the natural owner; decide before phase 4. +- **Event `summary` and `tags`** go out empty because Events has no such fields. Add them in a + later 2.x if the Website's event cards need them. +- **A "cancelled" state in Events** (shown as cancelled rather than disappearing) would map to + `status: "cancelled"`. Not in 2.4.0. diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 77680b1..fa39f04 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -1,6 +1,6 @@ # Handover — Cross Code, all products -Last updated: 2026-11-17. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03, +Last updated: 2026-11-18. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03, decisions table near the end). This file says where each phase stands and what comes next. Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events' are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and the Hub's are in @@ -24,22 +24,26 @@ for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)). | Phase | What | State | |-------|------|-------| | 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04. Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) | -| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first) | +| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). Deploy straight to the latest 2.1.x (below) | | 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.0: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) | -| 1d | Agent 1.0.0 + Hub 2.1.0 (+ 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). **Not rolled out** | -| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then | +| 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 | | 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 -1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md): Hub 2.1.0 (make and back up +1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) (with the latest patch + releases: Hub 2.1.1, agent 1.0.1, Events 2.3.1): Hub 2.1 (make and back up the job-signing key first) → the central server's agent (check `proxy_bind_addr = 127.0.0.1`) → each church server's agent → **adopt** the demo site, then each church (Link existing → Move 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), as in ROADMAP §9. +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. ## The VM test (2026-11-17) diff --git a/docs/ROADMAP-v3.md b/docs/ROADMAP-v3.md index 0b60409..ced4adf 100644 --- a/docs/ROADMAP-v3.md +++ b/docs/ROADMAP-v3.md @@ -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 | 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 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 | | 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 |