mr.zeroandClaude Opus 5
2bf0b20b77
Nothing said whether a release was finished. A pipeline step can fail, a
platform can gain a target, a title can be published from a laptop — and the
catalog happily serves a release with three of its seven assets. The only way
to find out was to open `/api/softwares/<name>/builds` one name at a time.
$ bin/rails warp_engine:builds:check
rabbitroller ebitengine v1.1.1 1/7
[x] html
[ ] win_x86
[ ] win_x64
[ ] linux_x64
[ ] linux_arm64
[-] mac_x64
[-] mac_arm64
The CI can build these and the release does not have them:
rabbitroller v1.1.1 (ebitengine): win_x86, win_x64, linux_x64, linux_arm64
5 softwares, 5 releases, 14/32 assets present, 16 missing from CI-built kinds
The third marker is the point. Two different questions were being conflated:
what the **updater** can ingest (`Platform#expected_kinds`) and what the
**pipeline** actually produces. For six of the seven platforms they are the
same list; for ebitengine they are not — the updater accepts macOS builds, the
Woodpecker builder cannot cross-compile them (osxcross), so `mac_x64` and
`mac_arm64` would be reported as gaps on every ebitengine release, for ever.
`[ ]` is now a real gap and `[-]` is "upload it by hand or not at all", so the
list stays worth reading.
That knowledge is data, next to the templates that produce it:
`PipelineConfig::BUILT_KINDS`, reachable through the adapter as
`built_kinds(platform)`. An adapter that cannot answer — no CI configured, a
platform with no builder — returns nil, and then nothing is excused: every
missing kind counts as a gap.
`WarpEngine::AssetCoverage` computes it (`#rows`, `#missing_rows`, `#totals`)
and `AssetCoverageChecklist` renders it, so the numbers are testable without a
terminal. Options are env vars: NAME, PLATFORM, RELEASES=all, ONLY=missing, and
STRICT=1 for a non-zero exit in CI. The default is the newest release per
software, using the same non-`dev-` rule the catalog API uses for "latest".
33 new examples, including two that keep BUILT_KINDS honest: every claimed kind
has to be a kind the updater knows, and has to appear in the platform's rendered
pipeline. Adding a platform without teaching this list about it fails the suite.
Ships in 0.8.0.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Teletype Games
Monorepo for the Teletype Games portal: a Vue 3 frontend, a Rails 8 API host app, and the reusable WarpEngine software-catalog engine.
Project structure
apps/
frontend/ # Vue 3 + Vite + TypeScript + Tailwind SPA
api/ # Rails 8 host app: TTG-specific API + ActiveAdmin shell
libs/
ruby/warp_engine/ # WarpEngine: mountable Rails engine (catalog, updater, admin resources)
The API is split in two layers:
- WarpEngine (
libs/ruby/warp_engine) owns the software catalog: models (softwares, releases, release assets, software-image links, platform links, download stats), the CI-callable/build/*publishing endpoints, the public read-only JSON API (/api/software*,/api/builds*,/api/download,/file/*) and the catalog ActiveAdmin resources. See its README. - The host app (
apps/api) owns everything TTG-specific: members, events, the image library (Image,/api/image/:id, the admin page — the engine only links to it through an adapter), the store registry, wiki proxy, RSS feeds, Devise/ActiveAdmin authentication, theming and assets. It consumes WarpEngine as a path gem and mounts it at/.
The store registry
GET /api/stores lists the stores a client can install from. The desktop
graphical client reads it on first run, which is why it is public: a client has
nobody to log in as.
[
{ "name": "Teletype Games", "catalogUrl": "https://teletypegames.org", "storeRepositoryUrl": null }
]
A Store row has two required fields — name and catalog_url — plus an
optional store_repository_url, maintained from ActiveAdmin ▸ 🛒 Stores;
db/seeds.rb creates our own.
A store does not need a repository. The store engine's own defaults already
cover the host-to-asset mapping, the install modes, the platforms and the
behaviour; what they cannot know is identity — a slug, a name and a catalog — and
that is what this row carries. With no repository the client derives the slug from
the catalog host, writes a small config and installs. Given one, it reads that
repository's config.json and points it at catalog_url, and that file remains the
authority on how the store behaves; a repository without a config file is treated
as no repository at all.
Every WarpEngine API response also carries a WarpEngine-Version header — the registry
above is the host's own endpoint and does not, because it is not part of the engine.
This lives in the host app on purpose, not in WarpEngine. The engine serves one catalog and has no business knowing which stores exist for it; who ships a store for a catalog is a property of the site.
| Model | apps/api/app/models/store.rb |
| Endpoint | apps/api/app/controllers/api/stores_controller.rb |
| Admin | apps/api/app/admin/stores.rb |
| Client | warp-engine-client |
Development environment
docker compose up -d
| Service | URL |
|---|---|
| Frontend | http://${WEBAPP_DOMAIN} |
| API | http://${WEBAPP_DOMAIN}/api |
| Admin | http://${WEBAPP_DOMAIN}/admin |
| API docs | http://${WEBAPP_DOMAIN}/api/swagger |
The api image is built from the repo root (so the libs/ path gems are visible
during bundle install) and mounts ./libs at runtime. After changing the
compose file or the Gemfile, rebuild with docker compose up -d --build api.
Testing
make api-test
Runs the host suite (apps/api, softwares_test DB), the WarpEngine suite
(dummy app, warp_engine_test DB) and a production-mode zeitwerk:check.
Individually:
docker exec -e RAILS_ENV=test api bundle exec rspec # host
docker exec -w /libs/ruby/warp_engine -e RAILS_ENV=test api bundle exec rspec # engine
JSON contract baselines for /api/software and /api/builds live in
apps/api/spec/snapshots/ — diff against them after refactors.
Linting
Backend (RuboCop)
docker compose run --rm --no-deps api bundle exec rubocop # check
docker compose run --rm --no-deps api bundle exec rubocop -A # autofix
Config: apps/api/.rubocop.yml (rubocop-rails-omakase preset)
Frontend (ESLint)
docker compose run --rm --no-deps frontend npm run lint # check
docker compose run --rm --no-deps frontend npm run lint:fix # autofix
Config: apps/frontend/eslint.config.js (ESLint 9 flat config, Vue + TypeScript)