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
6.6 KiB
Handover — Cross Code, all products
Last updated: 2026-11-17. 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) |
| 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
- Roll out, in the order in 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. - Deploy crosscode-site
v1.3.0(secure sign-in in the features and the brochure). - Archive
hope-eventsonce every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7). - 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:
adoptrefused a release with new migrations (it now applies them in the switch-over).- A failed migration blocked every later deploy (Prisma P3009; now marked rolled back).
- The agent install skipped the root's build tools (
npm ci --include-workspace-root). - A failed install's short name couldn't be used again.
- The Hub didn't save the servers settings (install defaults, port range, central IP).
- frpc only reads its admin lines when it starts (restarted once the first time).
- 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>. - Update and closing banners never reached Hub-installed sites (registration now links them).
- 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.mjsand the Hub'sfrontend/src/lib/tiers.ts(plusbackend/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>; thecrosscodescript 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
.envvariable goes in three env templates:apps/<product>/env.template.json,scripts/products/<product>.env.template.jsonand the Hub'senvTemplates/<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, andnpm run checkfirst. 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 withgit ls-remotebefore pushing again.