feat(ci): packaging, release and the frozen manifest
Phase 2 of docs/modules/rust/PLAN.md. Phase 1 built five guards and ran them by hand; this repo had no workflows at all, so nothing gated the branch that gets released and there was no way to release it. Three pieces: - **release.yml** — the derived-version engine link, installer and Module-uo already run (conventional-commit subjects since the newest tag; module.json's version survives as a floor; workflow_dispatch as the backdoor), assembling the bundle from an include list and publishing the tarball, the install manifest carrying its sha256, and SHA256SUMS. The tag is the number that ships and CI stamps it into the bundle's own module.json. - **pr-checks.yml** — server tests, check:imports, check:bundle, check:swagger, the client build, client tests and check:externals, plus frozen-manifest. - **frozen-manifest** — clones core at the sha pinned in ci/core-ref.json, generates its route table without this module and with it, and takes the difference. It ran locally against that exact ref: six routes, all documented, no core route moved. That is the first proof by a running core that /rust collides with nothing — phase 1 could only check it by reading, because core mounts /status and /version at a tier root where the loader's own collision probe cannot see them. The bundle carries no node_modules, because the shipped half declares no runtime dependencies (org lead, phase 2). checkBundle.js holds both halves of that: the include list still covers everything server/index.js reaches, and no dependency has appeared without the release learning to pack it. Verified by breaking it — dropping "model" from the list names the exact edit and exits 1. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
This commit is contained in:
62
README.md
62
README.md
@@ -52,6 +52,7 @@ both surfaces an operator can configure and then wait on, which is worse than an
|
||||
```bash
|
||||
npm ci --prefix server && npm test --prefix server
|
||||
npm run check:imports --prefix server
|
||||
npm run check:bundle --prefix server
|
||||
npm run check:swagger --prefix server
|
||||
npm ci --prefix client && npm run build --prefix client
|
||||
npm run check:externals --prefix client && npm test --prefix client
|
||||
@@ -66,11 +67,66 @@ Regenerate the OpenAPI fragment whenever a route or an annotation changes:
|
||||
npm run swagger --prefix server # writes swagger-fragment.json; commit it
|
||||
```
|
||||
|
||||
`.gitea/workflows/pr-checks.yml` runs all of the above on every pull request, plus one job this
|
||||
machine cannot run on its own: **frozen-manifest** clones core at the sha pinned in
|
||||
[`ci/core-ref.json`](ci/core-ref.json), generates its route table without this module and then with
|
||||
it, and takes the difference. That difference is the URL surface this module serves — checked
|
||||
against the committed [`routes.manifest.json`](routes.manifest.json), against the OpenAPI fragment
|
||||
in both directions, and against the rule that **a module may only add**. It is the only thing that
|
||||
can see whether `/rust` collides with one of the routes core mounts at a tier root (`/status`,
|
||||
`/version`), which the loader's own collision probe cannot find.
|
||||
|
||||
## How it reaches an operator
|
||||
|
||||
**An operator never builds anything.** A release is not source: it is the directory core's loader
|
||||
expects at `modules/rust/`, already assembled — the prebuilt client chunk, the schema fragment and
|
||||
the OpenAPI fragment, packed as they will be unpacked.
|
||||
|
||||
**Every merge to `main` carrying a releasable commit publishes a bundle.** The next version is
|
||||
computed from conventional-commit subjects since the newest `v*` tag, as in `link`, `installer` and
|
||||
`Module-uo`: `feat!:` or `BREAKING CHANGE` is a major, `feat:` a minor, `fix:` or `perf:` a patch,
|
||||
and a `main` that gained none of those cuts no release. The number that ships is the **tag**, and CI
|
||||
writes it into the `module.json` inside the bundle. `module.json`'s version survives as a **floor**:
|
||||
name a version there above the newest tag and that version releases, which is how you overrule the
|
||||
subjects. For a change with nothing releasable behind it — a widened `coreApi`, a new mount, a
|
||||
capability — run the **Release** workflow by hand (Actions → Release → Run workflow).
|
||||
|
||||
Each release carries:
|
||||
|
||||
| Asset | What it is |
|
||||
|---|---|
|
||||
| `module-rust-<version>.tar.gz` | the directory core expects at `modules/rust/`, already assembled |
|
||||
| `module-rust-<version>.json` | the install manifest: id, version, `coreApi`, the artifact's URL, size and **`sha256`** |
|
||||
| `SHA256SUMS` | the same hash, in the shape every other repo here publishes |
|
||||
|
||||
Releases are **unsigned**; the `sha256` is the trust anchor, and the website verifies it before
|
||||
unpacking. That is the model `installer`'s bundles already use, and a second trust model would be a
|
||||
second thing to get right.
|
||||
|
||||
The tarball is assembled from an **include** list ([`ci/bundle.json`](ci/bundle.json)), never an
|
||||
exclude list — an exclude list ships whatever it forgot. Tests, scripts, `client/src`, `ci/` and the
|
||||
dev dependencies are not in it. It carries **no `node_modules`**, because the shipped half declares
|
||||
no runtime dependencies: everything it needs arrives on `ctx`. `npm run check:bundle` holds both
|
||||
halves of that — that the list still covers every file `server/index.js` can reach, and that no
|
||||
runtime dependency has appeared without the release learning to pack it.
|
||||
|
||||
## Install it into a core
|
||||
|
||||
Copy the whole tree to `<website>/modules/rust/` and restart. **Copy, do not symlink** — the loader
|
||||
lists directory entries and asks each whether it is a directory; a symlink answers no and the module
|
||||
is skipped in complete silence.
|
||||
**From a release**, which is the supported path: in Admin → Modules, paste the URL of that release's
|
||||
`module-rust-<version>.json`, and restart when the panel offers. Core fetches the manifest, checks
|
||||
every URL and redirect hop against its own host allowlist, streams the artifact under a byte cap
|
||||
while hashing it, verifies the `sha256`, inspects the archive in full before unpacking it to a
|
||||
temporary directory, and only then moves it into `modules/rust/`. Nothing is written into the
|
||||
modules directory until every check has passed. The allowlist must contain
|
||||
`gitea.whitlocktech.com` — it is seeded from `MODULE_SOURCE_HOSTS` on a fresh install and is
|
||||
DB-owned from then on, edited on that same screen. **An empty allowlist forbids every install rather
|
||||
than permitting all of them.**
|
||||
|
||||
**From a working tree**, for development: copy the whole tree to `<website>/modules/rust/` and
|
||||
restart. **Copy, do not symlink** — the loader lists directory entries and asks each whether it is a
|
||||
directory; a symlink answers no and the module is skipped in complete silence.
|
||||
|
||||
Either way, the module appears when the process restarts: the volume is read at require time.
|
||||
|
||||
Then, in Admin → Rust, add a server: its name, the sidecar's base URL, and the token the sidecar
|
||||
printed on first start (`rust-link-sidecar --print-config`). **The token is write-only** — it is
|
||||
|
||||
Reference in New Issue
Block a user