Docs: agent 1.0 built (changes while building), handover, changelogs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 13:19:41 +02:00
co-authored by Claude Opus 5.5
parent 1eeaf4d94f
commit d61b3e5978
4 changed files with 59 additions and 1 deletions
+28
View File
@@ -8,6 +8,10 @@ This replaces the old rule "the Hub never deploys" (decisions 10 and 23). The pa
stays: **no site depends on the Hub to keep running**, and everything still goes through the
`crosscode` script (EVENTS-2.2-PLAN §4), which keeps working by hand over SSH.
**Built 2026-11-18** (crosscode-platform branch `feat/agent-1.0`, events-hub branch
`feat/servers-agent`; not merged or released). Waiting for the VM tests (§13). Where the build
differs from this plan, see [Changes while building](#changes-while-building).
## Contents
1. [The shape](#1-the-shape)
@@ -453,6 +457,30 @@ Central check: both ports are open in frps and only on 127.0.0.1.
5. Docs: CHANGELOGs, HANDOVER.md (1d done), `events-hub/deployment.md` (the job-signing key),
a server how-to in `apps/agent/README.md`.
## Changes while building
Made on 2026-11-18, while building; none changes what Joshua or a church sees.
1. **Config encryption** is X25519 + HKDF-SHA256 + AES-256-GCM (`x25519-hkdf-sha256-aes-256-gcm`)
instead of `x25519-xsalsa20-poly1305`: Node's built-in crypto has no XSalsa20, and this needs no
extra library on the servers. Same guarantee: only the server's private key opens it.
2. **Deployments, not new Install fields.** An `Install` row only exists once a site registers
with its licence, so the Hub keeps a `Deployment` per product per server (short name, domain,
ports, status), linked to its Install when the site registers. Installs made from the Hub
register by themselves: `HUB_LICENCE_KEY` in their `.env` (Events, on first start).
3. **The export key** goes to the Hub in the export job's report, so the Hub can email the link;
it's used once and never stored (job rows keep the report without it). The Hub still can't read
the stored file.
4. **Jobs are signed when the agent picks them up**, not when they're planned, so a scheduled job
carries the server configuration as it is at that moment.
5. **Uninstall runs as a batch of two** (export, then uninstall), so the uninstall never runs if
the export failed.
6. **Install behind frp** doesn't use nginx on the church server: frpc tunnels the app's two ports
straight to the central server (`crosscode install --frp`). The ports from the Hub are used for
`local_port` and `remote_port`.
7. **`crosscode install`** refuses a database or role that already exists, so it can never take
over (or, on a failed install, drop) another site's database.
## Decisions
Agreed with Joshua on 2026-11-12 (ROADMAP-v3 decisions 27–37):
+1 -1
View File
@@ -27,7 +27,7 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
| 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 | **Planned** 2026-11-12 in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) (ROADMAP decisions 27–37). Starts after 1b; can run alongside 1c |
| 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). |
| 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 |