Files
crosscode-platform/docs/EVENTS-2.2-PLAN.md
T

15 KiB

Cross Events 2.2.0 — moving into the monorepo

Phase 1b of ROADMAP-v3.md (§8 "Releases and updates", §9; decisions 21, 23, 24). Written 2026-11-05.

What 2.2.0 is: Cross Events moves from joshua/hope-events into this repo as apps/events, with its git history, and the crosscode script replaces scripts/deploy.sh and scripts/install.sh. It changes no features. If something breaks, the cause is the move. Churches see one line in What's new ("Nothing changes for you").

Done when:

  • events@2.2.0 is tagged here, and the Hub lists it under Cross Events.
  • Every existing install has been moved with crosscode adopt and reports 2.2.0.
  • hope-events is archived.
  • The test results match 2.1.1's.

Before starting

  • Hub 2.0.0 is deployed. Its release sync already reads events@… tags from this repo, with notes in apps/events/WHATS-NEW.md (events-hub/backend/src/utils/releaseSync.js). It also keeps the hope-events v… source for older releases. Hub 1.7 can't see events@ tags.
  • hope-events main is at 2.1.1 with nothing in flight, and frozen from step 1 on. A fix needed during the move goes in on the hope-events side as 2.1.2 and is merged in again (step 1 can be re-run).
  • Baseline: the result counts of 2.1.1's backend Jest run, frontend build and Playwright e2e run, so step 6 has something to compare against.
  • git-filter-repo installed on the dev machine (pip install git-filter-repo).

1. History: merge it in, with paths rewritten

On a fresh clone, so the working repo is never rewritten:

git clone https://c-git.crosscode.co.za/joshua/hope-events.git events-move
cd events-move
git tag -l | xargs git tag -d                  # v… tags stay in the archived repo
git filter-repo --to-subdirectory-filter apps/events
cd ../crosscode-platform
git checkout -b move/events
git remote add events-move ../events-move && git fetch events-move main
git merge --allow-unrelated-histories events-move/main \
  -m "Cross Events moves into the monorepo (apps/events), from hope-events <last commit hash>"
git remote remove events-move
  • Why filter-repo rather than git subtree add: every old commit then already has its apps/events/… path, so git log and git blame on a file show its whole history without --follow. Commit hashes change. The archived repo keeps the originals, and the merge message names the last one.
  • Old tags aren't brought over. Bare v2.1.1 tags would be ambiguous in a monorepo, and the Hub reads them from the archived repo. Product tags start at events@2.2.0.

2. Workspaces and the lockfile

  • Root package.json → "workspaces": ["packages/*", "apps/*", "apps/events/backend", "apps/events/frontend"]. apps/events itself is covered by apps/* (its root scripts and Playwright).
  • Rename the packages so workspace names are unique: @crosscode/events (was hope-events), @crosscode/events-backend, @crosscode/events-frontend. Nothing reads the names. The Hub reads the backend's version (backend/src/hub/report.js), and that stays. All three go to 2.2.0.
  • One lockfile at the root. Delete backend/package-lock.json and frontend/package-lock.json, then run npm install at the root. Versions must not drift: compare npm ls --all before and after (next, react, prisma, @prisma/client, express, typescript, jest, ts-jest, @sentry/nextjs, pg-boss, and anything else resolved differently). Pin anything that moved with overrides. Keep the existing shell-quote override at the root.
  • Hoisting traps to check:
    • Prisma's prisma-client-js generates into the hoisted node_modules/.prisma/client. That's fine while Events is the only Prisma app. Accounts (phase 3) must use its own generator output, otherwise the two overwrite each other locally. On servers each checkout builds only one app, so the problem doesn't arise there. Events keeps the default, so no imports change in 2.2.0.
    • Next.js 16 finds the workspace root from the lockfile. Once the nested lockfiles are gone, there's no "multiple lockfiles" warning, and next build traces files from the repo root. Check that .next still builds to apps/events/frontend/.next, and that NEXT_DIST_DIR (e2e) still works.
    • @types/node 20, TypeScript 5, Jest 30 and ESLint 10 are the same majors on both sides.
  • Lint: the root eslint . ignores apps/events/** (add it to globalIgnores). Events keeps its own configs: frontend/eslint.config.mjs, plus tsc for the backend. Moving Events onto the root lint is a later cleanup, not part of 2.2.0.
  • Root npm run check runs Events' scripts through --workspaces --if-present: backend test and typecheck, frontend build. Make sure the backend tests run with no database, as they do today. If any need one, give them their own script so the root check stays self-contained.

3. Inside apps/events

Paths mostly carry over, because everything in Events is relative to its own folder:

  • .gitignore moves to apps/events/.gitignore. Git reads a nested .gitignore relative to its own folder, so /ecosystem.config.js, backend/public/uploads/, backend/backups/ and backend/data/*.json keep working unchanged. Check with git status --ignored on a copy of a real install.
  • ecosystem.config.js uses __dirname + '/backend'. Placed in apps/events/, it needs no change. adopt rewrites only installs whose copy has absolute cwd paths.
  • Playwright (apps/events/playwright.config.ts) keeps its cwd: "backend" / "frontend". Run it from apps/events.
  • Docs: ROADMAP-v3.md and hub-protocol.md already live in the root docs/. Remove their pointer stubs from apps/events/docs/ in the merge. Code comments that cite docs/hub-protocol.md then point at the root copy. apps/events/docs/HANDOVER.md keeps the Events-only parts (where the code lives, known gaps), and the cross-product status lives in the root HANDOVER.md.
  • CHANGELOG.md and WHATS-NEW.md stay in apps/events/ (the Hub reads apps/events/WHATS-NEW.md). The 2.2.0 entry in WHATS-NEW.md has no — requires.
  • README.md and DEPLOYMENT.md: rewrite the deploy and install sections for crosscode. The nginx and PM2 background stays.
  • scripts/deploy.sh and scripts/install.sh are removed from apps/events. The archived repo keeps them for installs that haven't moved yet.

4. The crosscode script

It lives in this repo's root scripts/. It's bash, like today's scripts, and is checked with shellcheck. On a server it's a checkout of main in /opt/crosscode/tools, updated with git pull --ff-only at the start of every run, then re-run from a copy (as deploy.sh does today, so a checkout never changes the running script).

scripts/
  crosscode                 entry: self-update, re-run from a copy, dispatch, `help`
  lib/common.sh             logging, root/app-user checks, church.env read/write, tag lookup
  lib/deploy.sh             checks → per product in order → summary
  lib/install.sh            new church (from today's install.sh)
  lib/adopt.sh              existing Events install → monorepo
  lib/status.sh
  products/events.sh        the product's hooks (below); accounts.sh, website.sh, app.sh follow
  tests/                    bats tests for the parts that don't need a server

Product hooks. Each products/<name>.sh defines backup, install_deps (npm ci --include=dev -w apps/events/backend -w apps/events/frontend), migrate, build, pm2_names, health_url and rollback_build. With hooks, adding Accounts in phase 3 means adding a file, not rewriting the deploy. For Events they come from today's deploy.sh: the backup through backupUtils.runBackup(), prisma migrate deploy, the backend tsc build and next build.

church.env (/var/www/sites/<church>/church.env, mode 600, owned by root):

CHURCH=hopefamily
PRODUCTS="events"                       # accounts website app as they're added
ADDRESS=hopefamily.co.za                # or hopefamily.crosscode.co.za
EVENTS_DIR=/var/www/sites/hopefamily/events
EVENTS_DOMAIN=events.hopefamily.co.za
EVENTS_PM2="hope-events-backend hope-events-frontend"
EVENTS_PORTS="5000 3000"                # api web
EVENTS_DB=hope_events
EVENTS_USER=hopeevents

Secrets stay in each product's own .env, never in church.env.

Commands in 2.2.0:

Command In 2.2.0
deploy <church> [events] Yes. Accounts is skipped while a church has none (§8). Tags are events@x.y.z, newest by version (git tag -l 'events@*' --sort=-v:refname)
deploy … --version events@x.y.z, --main, --check Yes
deploy --every-church … Yes (it's a loop over /var/www/sites/*/church.env)
status [<church>] Yes: version from /health, latest tag, DB, jobs, last backup
install <church> --products events --domain … Yes, for Events only (from today's install.sh: Node 24, PostgreSQL, PM2, nginx, certbot); it writes church.env
adopt <church> --events-dir … Yes (section 5)
adopt <church> --undo New, proposed: goes back to the old folder and the 2.1.x it ran, within the days the old folder is kept
add <church> <product> Later (phase 3), when there's a second product to add

Requirement check (decision 24): before anything is touched, read the target version's heading in apps/<product>/WHATS-NEW.md. Refuse the deploy if a — requires <product> <version> isn't met by the installed sibling or by this same run. Nothing in 2.2.0 requires anything, but the check is built and tested now.

A deploy, per product (as deploy.sh today): refuse if files were changed by hand → database backup → git fetch --tags and check out the tag (detached) → install and build that app only → migrations → pm2 reload → poll /health until it reports the new version (60 s). On failure that product goes back to its previous tag and rebuilds, and the run stops. The summary lists each product as updated, rolled back or not reached.

5. crosscode adopt (once per existing install)

Proposed change to ROADMAP §8: build the new checkout next to the running install, then switch over, instead of moving the running folder. Moving the folder underneath running PM2 processes breaks anything they read from disk later (Next.js pages, uploads), so the site would be down for the whole build. Building next to it keeps the old install untouched, which makes rolling back simply "start the old one again".

  1. Checks: the old folder is a hope-events checkout at a v2.1.x tag with no files changed by hand, and /var/www/sites/<church>/events doesn't exist (or is already an adopted checkout, in which case stop: nothing to do).
  2. Read what the install already has: the PM2 names and ports from ecosystem.config.js, and the database name from backend/.env DATABASE_URL. Write church.env.
  3. New checkout of this repo at events@2.2.0 in /var/www/sites/<church>/events, owned by the app user.
  4. Copy the install's own files into apps/events/: backend/.env, frontend/.env*, ecosystem.config.js (with absolute cwds rewritten), backend/data/*.json, and backend/backups/. Then rsync -a backend/public/uploads/, which may be large; the old site is still serving meanwhile.
  5. Build (npm ci -w …, backend build, next build). The old install keeps running.
  6. Switch over (the only downtime, a few seconds): database backup → a final rsync -a --delete of the uploads and data/*.json → prisma migrate status must show nothing pending (2.2.0 adds no migrations; refuse if it does) → pm2 delete the two names → pm2 start ecosystem.config.js from the new folder → pm2 save → /health reports 2.2.0.
  7. On failure at step 6: pm2 delete → pm2 start from the old folder → pm2 save. Nothing in the old folder was changed, so it comes back exactly as it was.
  8. Keep the old folder, renamed <old>.pre-2.2.0, for 14 days. adopt --undo uses it. After that, crosscode status reminds you to remove it.

The nginx config doesn't change (it only proxies to ports), and neither do the PM2 names, the database or its name.

6. Testing

  • Events, unchanged behaviour: backend Jest, tsc --noEmit, frontend build and the Playwright e2e run, all from the monorepo. They should give the same counts as the 2.1.1 baseline.
  • Script: shellcheck, plus bats tests for tag lookup, the — requires parsing, church.env reading and writing, and the rewriting of ecosystem.config.js.
  • On a throwaway Ubuntu 24.04 VM (e.g. multipass), in this order:
    1. install.sh from the archived repo at v2.1.1. Add demo data and a few uploads.
    2. crosscode adopt → 2.2.0 works, the uploads are there, and the database is unchanged.
    3. adopt --undo → back on 2.1.1. Then adopt again.
    4. crosscode deploy <church> events --version events@2.2.0-test with a broken migration on a test tag → it rolls back to 2.2.0 and the site stays up.
    5. A file changed by hand → deploy --check refuses it.
    6. A second church with crosscode install on the same VM → separate databases, .env files, uploads and PM2 names. deploy --every-church updates both.
    7. crosscode status for both.
    8. The Hub (local, port 5200) sees the install's heartbeat as 2.2.0, and events@2.2.0 under Releases.

7. Rolling it out

  1. hope-events, last commit on main: README "Moved to crosscode-platform/apps/events; this repo only keeps 2.1.x for installs that haven't moved". No tag.
  2. Here: merge move/events → npm run check → tag events@2.2.0 → push with tags. Remove any test tags first.
  3. Hub: run release sync. Check that Cross Events shows 2.2.0 and the older v… releases are still listed.
  4. Servers: set up /opt/crosscode/tools. Adopt a staging copy first, then each real install one at a time, checking crosscode status after each. Installs on 2.1.1 see 2.2.0 on the Hub. Their "Request update" is answered with adopt, not deploy.
  5. When every install reports 2.2.0: archive hope-events on Gitea (read-only; cloning and fetching still work, so adopt --undo and old installs keep working).
  6. crosscode-site: nothing changes (ROADMAP §9).
  7. Docs: a 2.2.0 entry in apps/events/CHANGELOG.md and the root CHANGELOG.md, and the root HANDOVER.md updated with 1b done and 1c (2.3.0, authenticator app 2FA) next.

Open questions

  1. Build next to the old install and switch over (section 5, recommended), or move the folder as ROADMAP §8 says? If the switch-over is agreed, §8 gets updated to match.
  2. adopt --undo: build it (recommended; it's small once the old folder is kept) or not?
  3. Do any Events backend tests need a database, which would affect the root npm run check? (Answered while doing section 2.)