wtclaude
b287728c19
All checks were successful
PR checks / checks (pull_request) Successful in 9m11s
checkFacts needs to read link, servuo-plugins, website and installer, and the automatic per-run token is scoped to this repo alone. Rather than mint a new secret, the workflow uses REGISTRY_TOKEN, which already exists at the org level with the right permissions. The secret is named for the registry and the script reads GITEA_TOKEN; the mapping stays in the workflow so the script keeps asking for what it actually wants -- a Gitea token -- rather than this org's secret name. Co-Authored-By: Claude <noreply@anthropic.com>
107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# runicgateway.com
|
|
|
|
The public marketing and documentation site for [Runic Gateway][org] — the platform that puts a
|
|
private game server's live state on a public website without ever exposing the game to the internet.
|
|
|
|
Two audiences: **server administrators** who want to understand and install the platform, and
|
|
**developers** who want to build modules and integrations for it. A third arrives with the Android
|
|
closed beta: **players**, who want the app.
|
|
|
|
**The design of record is [`PLAN.md`](PLAN.md).** It is not a sketch — it carries the verified
|
|
platform state, the org lead's decisions, the information architecture, and the build phases. Read
|
|
it before changing anything here.
|
|
|
|
**Status: phase 1 of 12 — the foundation.** The scaffold, the token file, the typography, the layout
|
|
shell and the two build-time checks are in place. The homepage is phase 3, the marketing pages
|
|
phase 4, and the documentation — the installation path, which is the priority of the whole project —
|
|
phase 7.
|
|
|
|
---
|
|
|
|
## Running it
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev # http://localhost:4321
|
|
```
|
|
|
|
```bash
|
|
npm run build # → dist/ (prerendered pages + the Node server entry)
|
|
npm start # serve the built site
|
|
```
|
|
|
|
Node 22 LTS or newer.
|
|
|
|
## The checks, and why they are not optional
|
|
|
|
Two of them, both from `PLAN.md` §12. Neither is a linter; each one enforces a promise the site
|
|
makes that would otherwise decay quietly.
|
|
|
|
```bash
|
|
npm run check:tokens # no colour literal outside the token file
|
|
GITEA_TOKEN=<token> npm run check:facts # every version agrees with its authority
|
|
npm run check # astro check
|
|
npm run verify # all of the above, then a production build
|
|
```
|
|
|
|
**`checkFacts.mjs`** re-reads every version, protocol number and bundle tag in
|
|
`src/data/platform.json` from its source of truth over the Gitea API — the sidecar's
|
|
`PROTOCOL_VERSION`, the overlay's `overlay.toml`, the website's `MODULE_API_VERSION`, the installer's
|
|
published bundle manifest, and each repository's latest release — and fails on any disagreement.
|
|
|
|
When the platform moves, this repository goes red so that someone updates the site. **That failure is
|
|
the feature**, the same mechanism and the same intent as the Integration Kit's `checkCoreApi.js`. §1
|
|
of the plan records what it is guarding against: an earlier draft confidently stated the platform was
|
|
on protocol 3, because every checkout in the workspace sat on a feature branch whose local `main` had
|
|
never been fetched.
|
|
|
|
It needs a token — anonymous raw fetches fail on this Gitea instance, and a check that silently skips
|
|
itself is worse than no check at all. It must be able to read the other repositories in the
|
|
organisation, not just this one. CI already has this: the workflow maps the org-level
|
|
`REGISTRY_TOKEN` secret into `GITEA_TOKEN` for that step.
|
|
|
|
**`checkTokens.mjs`** fails the build if a colour literal appears anywhere in `src/` outside
|
|
`src/styles/tokens.css`. §7 promises that recolouring the site is a file copy and a container
|
|
restart; a mounted `theme.css` can only redefine custom properties, so a literal in a component is a
|
|
piece of the site an operator can never reach. Without the check, "one CSS file changes the
|
|
appearance" becomes "one CSS file changes most of the appearance".
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
data/platform.json Every externally-sourced fact. No version is written in prose.
|
|
styles/tokens.css THE token file — the only place a colour literal may appear.
|
|
styles/global.css The layout shell, built entirely from tokens.
|
|
styles/starlight.css Restates our tokens as Starlight's, so the docs cannot drift.
|
|
layouts/, components/ The marketing chrome.
|
|
pages/ Marketing routes.
|
|
content/docs/docs/ Documentation. The extra level mounts Starlight at /docs.
|
|
lib/brand.mjs The single accessor for brand text.
|
|
lib/tokens.mjs Reads tokens.css at build time, for the few values that leave CSS.
|
|
config/sidebar.mjs The documentation journey, and the planned tree behind it.
|
|
brand-default/ The stock brand, baked into the image and always complete.
|
|
scripts/ The build-time checks.
|
|
```
|
|
|
|
Two directories are bind mounts at runtime and are **not** in the repository: `brand/` overrides
|
|
anything in `brand-default/` per file, and `data/` holds the beta signup store. See `PLAN.md` §6
|
|
and §7.
|
|
|
|
## Contributing
|
|
|
|
Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`) and use
|
|
[Conventional Commits](https://www.conventionalcommits.org/). Run `npm run verify` before opening a
|
|
pull request.
|
|
|
|
**AI-assisted contributions must be disclosed**, per org policy: tick the box in the pull request
|
|
template naming the tool, and mark AI-authored commits with a trailer such as
|
|
`Co-Authored-By: Claude <noreply@anthropic.com>`. Undisclosed AI-generated contributions may be
|
|
closed.
|
|
|
|
## Licence
|
|
|
|
GPL-3.0-or-later, in common with every repository in the organisation. See [LICENSE](LICENSE).
|
|
|
|
[org]: https://gitea.whitlocktech.com/RunicGateway
|