docs: handover after the 2.3.0 / agent 1.0 / Hub 2.1 release

Root HANDOVER: phases 1b–1d released and VM tested, the nine bugs the VM
test found, rollout next. Events HANDOVER: 2.3.0, where two-factor and the
Hub-install pieces live. AGENT-1.0-PLAN and EVENTS-2.2-PLAN: tested and
released, the VM changes; ROADMAP §9 marked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ls1vMdni7EfytGYqQTprME
This commit is contained in:
2026-11-17 22:41:10 +02:00
co-authored by Claude Opus 5.5
parent d985a4c853
commit a286f8abce
5 changed files with 107 additions and 40 deletions
+54 -26
View File
@@ -1,21 +1,21 @@
# Handover — Cross Code, all products
Last updated: 2026-11-12. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
Last updated: 2026-11-17. **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 `hope-events/docs/HANDOVER.md` (`apps/events/docs/HANDOVER.md` from Events 2.2.0), and
the Hub's are in `events-hub/docs/`.
are in [`apps/events/docs/HANDOVER.md`](../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](./hub-protocol.md), with a copy in `events-hub`), this handover and the plans
for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
([hub-protocol.md](./hub-protocol.md), with a copy in `events-hub`), this handover, the plans
for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
## Repos
| Repo | What |
|------|------|
| `joshua/crosscode-platform` (this one) | Contracts, the apps (Accounts, Website, App, and Events from 2.2.0), shared packages, the `crosscode` script (from Events 2.2.0), the server agent (`apps/agent`, phase 1d), and these docs |
| `joshua/hope-events` | Cross Events up to 2.1.x. Archived after the 2.2.0 move |
| `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) |
@@ -23,26 +23,44 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
| Phase | What | State |
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04 (`contracts@1.0.0`, `contracts@1.1.0`). Not published to a registry (decision 22): the Hub gets a packed release committed to its repo |
| 1 | Hub 2.0.0 | **Released** 2026-11-05 (`events-hub` `v2.0.0`; `docs/HUB-2.0-PLAN.md` there). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). crosscode-site's address prices are merged, **not deployed yet** |
| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **In progress.** Planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). **Steps 1–3 done 2026-11-12** (merged into `main`): history merged in under `apps/events` (from `hope-events` `e6c9670`), workspaces and one root lockfile with versions pinned to 2.1.1, same test results as 2.1.1 (711 backend tests, typecheck, both builds). **The `crosscode` script and `adopt` (§4–5) are written** (branch `feat/crosscode-script`, 2026-11-12; shellcheck and 47 bats tests pass, not yet run on a server). **Tagged `events@2.2.0` on 2026-11-17, before the VM testing (Joshua's call), with two additions: AI use in tokens and the backend under `/api` (Hub `v2.0.1` and crosscode-site `v1.2.0` released with them).** **Still to do:** VM testing (§6) of the tagged release, adopting each install, archiving `hope-events` (§7). Until then servers keep deploying from `hope-events` `v2.1.1`, and **Events work happens here** (`hope-events` is frozen; a hotfix there as 2.1.2 is cherry-picked into `apps/events`) |
| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | TOTP not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`). |
| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.3.0): server agent, installs / scheduled updates / uninstalls from the Hub, server stats | **Built 2026-11-18, not released.** crosscode-platform branch `feat/agent-1.0` (contracts 1.3.0, the crosscode script with `--json`, env templates, frpc, restart / export / uninstall / purge, Events env template + export + `HUB_LICENCE_KEY`, `apps/agent`), events-hub branch `feat/servers-agent` (Hub 2.1.0). All unit and script tests pass. **Still to do:** the VM tests (AGENT-1.0-PLAN §13, together with EVENTS-2.2-PLAN §6), then release and roll out (§14). |
| 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) |
| 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 |
| 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. **Deploy Hub 2.0.0** and **crosscode-site** (the address prices). This finishes phase 1 and is
needed before 2.2.0, because Hub 1.7 can't see `events@…` tags.
2. **Cross Events 2.2.0**: [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). Decided 2026-11-05:
`adopt` builds next to the running install and switches over, and `adopt --undo` is built
(ROADMAP decisions 25–26).
3. **Agent 1.0.0 + Hub 2.1.0** (phase 1d): [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). Before the
first install through it: check `proxy_bind_addr = 127.0.0.1` in `frps.ini` on the central
server (worth doing now: without it, tunnel ports such as `:5000` may be reachable straight from
the internet), and set each server's database settings and `TRUST_PROXY` in the Hub.
4. **Cross Events 2.3.0** (authenticator app 2FA), then 2.4.0, as in ROADMAP §9.
1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md): Hub 2.1.0 (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.
## 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
@@ -51,10 +69,20 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
`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>`.
`/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").
- **Releasing:** branch → merge → tag (`<product>@<version>`) → push, with a CHANGELOG entry, and
`npm run check` first. Pushes to c-git often fail authentication the first time; retry once.
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.