93 lines
7.8 KiB
Markdown
93 lines
7.8 KiB
Markdown
# Handover — Cross Code, all products
|
||
|
||
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
|
||
`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, 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 (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](./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 | Accounts 1.0.0 (+ contracts 1.5.0, Hub 2.3.0) | **Planned** 2026-11-18: [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md), eight decisions to confirm before building |
|
||
| 4–7 | 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) (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.
|