Files
crosscode-platform/docs/HANDOVER.md
T
joshuaandClaude Opus 5.5 716d47242a 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>
2026-11-18 12:58:50 +02:00

7.6 KiB
Raw Blame History

Handover — Cross Code, all products

Last updated: 2026-11-18. The plan is 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, and the Hub's are in events-hub/docs/ and events-hub/deployment.md.

The docs for every product are here in docs/: the roadmap, the Hub protocol (hub-protocol.md, with a copy in events-hub), this handover, the plans for each phase and the rollout checklist (ROLLOUT-1.0.md).

Repos

Repo What
joshua/crosscode-platform (this one) Contracts, the apps (Events from 2.2.0; Accounts, Website and App to come), shared packages, the crosscode script (scripts/), the server agent (apps/agent), and these docs
joshua/hope-events Cross Events up to 2.1.x. Frozen; archived once every install is adopted (EVENTS-2.2-PLAN §7)
joshua/events-hub Cross Code Hub. Its own server, its own scripts/deploy.sh
joshua/crosscode-site crosscode.co.za. Updated at the end of every phase that changes what it says (ROADMAP §9)

Where each phase stands (ROADMAP §9)

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). 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.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) Built 2026-11-18 (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

  1. Roll out, in the order in 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) 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)

Everything above was run on a WSL Ubuntu 24.04 VM before release: a church server, a "central" network namespace running frps with proxy_bind_addr, the Hub (feat/servers-agent) and local git mirrors standing in for c-git. It found nine bugs, all fixed with tests before tagging. None lost data, because each failed safely:

  1. adopt refused a release with new migrations (it now applies them in the switch-over).
  2. A failed migration blocked every later deploy (Prisma P3009; now marked rolled back).
  3. The agent install skipped the root's build tools (npm ci --include-workspace-root).
  4. A failed install's short name couldn't be used again.
  5. The Hub didn't save the servers settings (install defaults, port range, central IP).
  6. frpc only reads its admin lines when it starts (restarted once the first time).
  7. A site's PM2 belonged to the agent's service, so stopping or updating the agent took down every site it had installed. PM2 now always runs under pm2-<user>.
  8. Update and closing banners never reached Hub-installed sites (registration now links them).
  9. A moved tag blocked a church's deploys (tags are fetched with --force).

Not covered by the VM: FASTPANEL, real DNS, Let's Encrypt. Hence the throwaway install in the rollout.

Things to remember across phases

  • Before selling the Website or App: put the ROADMAP §10 prices in crosscode-site/src/data/pricing.mjs and the Hub's frontend/src/lib/tiers.ts (plus backend/src/utils/billing/tiers.js) in the same phase, so the site and the Hub never disagree.
  • A phase isn't done until crosscode-site matches it (ROADMAP §9, "Updating crosscode-site").
  • Servers stay PM2 + nginx (no Docker), with one database per product per church, under /var/www/sites/<church>/<product>. Each site user's PM2 runs as a systemd unit, pm2-<user>; the crosscode script makes sure of it before any PM2 command.
  • The agent pins the Hub's job key when it joins. Back up events-hub/backend/keys/ (licence and job keys); replacing the job key means every server joins again.
  • A new .env variable goes in three env templates: apps/<product>/env.template.json, scripts/products/<product>.env.template.json and the Hub's envTemplates/<product>.json.
  • A new Events install never takes over an existing database: moving an existing site is adopt, not a New install pointed at the old database.
  • Prisma in the monorepo: each app other than Events sets its own generator output, so hoisted clients don't overwrite each other (EVENTS-2.2-PLAN §2).
  • AI for a church: set the licence's monthly AI cap above R0 on the Hub; with no cap the buttons don't show (rules in Events' handover, "AI rules"). Churches see tokens; only the Hub shows rand (markup 15% by default).
  • Releasing: branch → merge → tag (<product>@<version> here, v<version> in events-hub and crosscode-site) → push, with a CHANGELOG entry, and npm run check first. Pushes to c-git often fail authentication the first time; retry once. A push can also hang waiting on a login prompt after it has already gone through: check with git ls-remote before pushing again.