warp-engine-client/README.md

warp-engine-client — the WarpEngine Client app

The client for a WarpEngine store: the catalog as a grid of cards, one click to install a title into your own application menu, one to play it, one to remove it. Linux, macOS and Windows.

The store engine is part of this application. Reading the catalog, choosing which release fits this machine, unpacking it, writing the menu entry and remembering what went where all happen in process — there is no interpreter to find and no child process to parse. What lands on disk has not changed: config.json and state.json keep the shape the shell engine wrote, so a machine whose library was installed by the CLI keeps it, and the engine's own defaults still decide everything a store does not configure.

That also makes this the only install path that needs nothing of the machine. The shell store's installer was curl … | sh, which Windows does not have.

Which store it installs is not baked in: the client asks a registry — GET /api/stores on the site — and each record says what the store is called, which catalog it serves and where its configuration lives.

What it needs

• Nothing. No interpreter, no package manager, no admin rights: the app carries its own runtime and the store installs under your own user account.

To develop it you also need Node 22 or newer — see below — and nothing else: the toolchain (TypeScript, ESLint, esbuild, electron-builder) installs with make setup.

Install

Grab the package for your machine from the releases and open it. On first run, if there is no store on the machine yet, the window offers to download one — that is the whole setup.

Opening it on macOS

The build is ad-hoc signed but not notarised, so macOS asks before running a copy that came from a browser. The reliable way through:

xattr -dr com.apple.quarantine "/Applications/WarpEngine Client.app"

If macOS offers Open Anyway under System Settings ▸ Privacy & Security after a blocked attempt, that works as well. Notarisation is the only thing that removes the step entirely, and it needs a paid Apple Developer ID.

Nothing the store itself downloads is affected: the app fetches those files over its own HTTP client, which does not set the quarantine flag.

v1.0.0 could not be opened at all — it reported "is damaged". The bundle had never been signed; only its main executable carried the linker's ad-hoc signature, so there was no resource seal and Gatekeeper refused it outright rather than asking. scripts/after-pack.js signs the bundle during the build now, and the result verifies as valid on disk.

Which store it installs

On first run the client fetches the registry and offers what it finds. One store and there is nothing to decide; several and the setup screen shows a picker.

[
  {
    "name": "Teletype Games",
    "catalogUrl": "https://teletypegames.org",
    "storeRepositoryUrl": "https://git.teletypegames.org/stores/ttg-desktop-store",
    "config": { "store": { "id": "ttg" }, "paths": { "subfolder": "teletypegames" } }
  },
  { "name": "Some Other Store", "catalogUrl": "https://games.example.org",
    "storeRepositoryUrl": null, "config": null }
]

A store needs nothing of its own. A name and a catalog are enough: the store engine's built-in defaults already cover the host-to-asset mapping, the install modes, the platforms and the behaviour, so what is actually missing from them is identity — a slug, a name and a catalog URL — and that is exactly what a registry record carries. With config and storeRepositoryUrl both null the client writes a three-section config and the store installs.

Where a store's configuration comes from, in the order the client asks:

1. config on the registry record — the store's own configuration, in the same shape a store's config.json had, because it is that file moved into the registry. It costs no request: it arrived with the store list.
2. storeRepositoryUrl → …/raw/branch/master/config.json — the same thing in its older home, read for a registry whose stores have not moved over yet. A repository without a config.json is treated as no repository at all.
3. the engine's defaults — when there is neither.

Two fields the record always decides, whatever the config says:

• catalogUrl and name override the config's own store.base_url and store.name. The registry says which catalog this store is for, so it wins.
• the store id — which names the store home and the folder games land in — comes from the config's store.id when it sets one; otherwise from the repository name (ttg-desktop-store becomes ttg), then the catalog host (teletypegames.org becomes teletypegames), then the display name.

The window never supplies a config. It is handed stores to show and hands one back to install, but only as an identity: RegistryStoreDtoMapper.toModel drops the config, and StoreProvisioningService reads the record again from the registry before installing. A config decides where files are written and which subtree the store may later delete from, so it must not be something the renderer can set — the same rule as GameDto carrying no paths.

What the defaults produce, for a record with no repository: the games land in a folder named after the store id, and released, archived and demo titles are listed — a catalog that publishes a demo means it to be played.

The registry address is the single thing about a particular site left in the client, and it is decided in three places, most specific first:

STORES_API=http://127.0.0.1:8731/stores npm start   # runtime: for trying something out
make dist STORES_API=https://games.example.org/api/stores   # build: for shipping it

The build variant is baked into the packaged app's own package.json (warpEngine.registryUrl, written by electron-builder --config.extraMetadata), so a client built for somebody else's catalog needs no source change and no environment on the user's machine. With neither set, the address is ours.

Adding a store is therefore a database row on the site — see its ActiveAdmin panel — and not a release of this app.

Use

Everything that is not a title lives in the side menu on the left, and the ☰ button in the bar folds it away — the state is remembered between runs.

• Stores lists every store on this machine, the open one marked. Clicking another switches to it: the grid, the categories and the folders all follow, and the client reopens on that store next time. Two stores installed from the same catalog into different folders show their folder instead of their id, because the id would not tell them apart. Add a store… brings up the registry picker, the same one the first run offers.
• Actions holds Refresh, which re-reads the catalog. Titles are installed one at a time from their own cards; there is no install-everything button.
• Categories narrows the grid, one category at a time, with the count next to each: Everything, Installed, Updates, Not installed, then a row per platform (godot, tic80, love, …) and per kind (native or hosted). The axes are built from what the catalog actually contains — a platform with no titles is not listed, and a category that disappears under you falls back to Everything rather than leaving an empty grid. There is no genre in a WarpEngine catalog, so these are the categories there are.
• Log opens the store's own output — its words, verbatim — together with the two folders everything lands in. Off screen until asked for: the window has no footer, because a permanent bar of absolute paths is not what a store is for.
• Language follows the system and can be switched; English and Hungarian.

In the grid, a card's button is Install, Update, or Play / Open once it is there. Remove takes a title back out. Each card says whether it is native — unpacked and run locally, works offline — or hosted: a browser build the catalog serves rather than packages, so its entry opens a page and needs the network.

Everything in the catalog is listed, including what this machine cannot install. Those cards are dimmed, carry an unsupported platform or no build for this machine badge with the engine's own explanation under it, and have nothing to press. A store that hides them leaves you wondering whether the catalog is small or your machine is unusual; this way it says which. They have a category of their own — Not for this machine — and they are left out of the native/hosted counts, because a title with no build has no mode to be counted under.

Every card carries a band of box art the same height — the first letter of the title when the catalog has no image — so titles and buttons line up across a row. Until this was photographed, the grid was quietly broken: the rows split the window's height evenly instead of following their content, which collapsed the art to nothing and clipped the buttons out of sight.

While the store is working, only the things that would start a second call are disabled: the menu, the log drawer and the category filters keep working, because they change what is on screen and nothing on disk.

Anything installed from the window is a normal menu entry, so it also shows up in your launcher, Dock or Start menu — the app does not have to be running to play.

Development

make is the front door; it wraps the npm scripts so the useful sequences have names. make on its own lists everything.

Target	What it does
make setup	install the dependencies (checks the Node version first)
make build	compile TypeScript, bundle the preload and the renderer
make typecheck	type-check everything, emitting nothing
make lint	the strict rule set (lint-fix fixes what it can)
make check	typecheck, lint and both test suites — the gate
make start	run the app against whatever store is installed
make smoke	drive the store with no window and no Electron at all
make uitest	load the window once and report what rendered
SELFTEST_SHOT=shot.png npm run uitest	the same, and the window photographs itself into that file
make test	both test suites
make dist	package for this machine (dist-mac, dist-win, dist-linux to pick)
make publish	upload the packages already in dist/ to the Gitea release
make release	package and publish in one go
make clean	remove build/ and the packages (distclean also drops node_modules)
make version	the versions involved, including whether tea is there

The npm scripts still work directly (npm start, npm run dist:mac) — the Makefile adds no logic of its own beyond the release step. Every script that runs the app builds first, so there is no way to test a stale bundle.

Continuous integration

.woodpecker.yaml builds the Linux and Windows packages, and on a tag attaches them to the Gitea release. The pipeline is in this repository rather than served by the update server's /build/config extension: that extension serves game-platform pipelines, which build a cartridge and publish it into the site's catalog, and this builds an application and publishes to a release.

Step	Image	What it does
check	electronuserland/builder:22	npm ci, type-check, lint, and the smoke test
linux	electronuserland/builder:22	AppImage and deb
windows	electronuserland/builder:22-wine	the NSIS installer and the portable exe, built through Wine
release	alpine	on a tag only: creates the release and attaches what this pipeline built

macOS stays a local build. Apple's toolchain and its signing only exist on a Mac. So the whole of a release is:

1. bump the version, commit, and push the tag: git tag v1.4.0 && git push origin v1.4.0;
2. the pipeline builds Linux and Windows, creates the release with RELEASE_NOTES.md as its body, and attaches those four packages;
3. on a Mac, make release builds the macOS package and pushes it onto the same release.

The window test is local as well: it needs a display and a store on the machine.

The release step needs a gitea_token repository secret — a Gitea token with write access to this repository:

woodpecker-cli repo secret add --repository stores/warp-engine-client \
  --name gitea_token --value <token> --event tag

Woodpecker does hand steps a forge credential of its own, and the script uses it when the secret is absent, but that is not something to rely on: a manual build has it and a build started by the tag webhook does not, which is how the first tag build failed — after building all four packages. Gitea takes either credential as token … or Bearer … depending on how it was issued, so the script probes which of the two /user accepts instead of assuming, and logs which one it used.

There are two publishers on purpose: scripts/release.sh drives tea, which is logged in on a workstation, and scripts/ci-upload.sh speaks the API with whatever credential CI has. Each is short enough to read in full; one script with two ways to authenticate would not be.

Both build steps end by checking what they produced: a package under 10 MB did not finish. That check exists because a half-finished Wine build leaves a stub named like the real installer — 162 KB of it — and ls is perfectly happy with that.

The Windows step cannot be rehearsed on an Apple Silicon Mac. Wine assumes 4 KB memory pages and this host has 16 KB ones, so an emulated amd64 container dies with anon_mmap_fixed: Assertion failed. It is a property of the machine, not of the pipeline; the x86_64 runner is where that step is proven. The Linux step was rehearsed locally in the same image and produced both packages.

The Windows installer is not signed: Windows will warn about an unknown publisher until there is a code-signing certificate. Linux packages carry no signature by convention.

Publishing a release

make release

This is the macOS half of a release; the Linux and Windows packages come from the pipeline when the tag is pushed (see above). The tag comes from package.json, so npm version patch is the only place a version is set. The release is created if it is not there yet — either half can go first — and an attachment whose name is already on it is replaced rather than refused, so a rebuild and a second make publish lands rather than erroring.

Release notes come from RELEASE_NOTES.md when the file is present, otherwise the release gets a one-line note. The repository is read from origin, so a fork publishes to the fork.

Each upload is retried up to three times, and the existing attachment is dropped before every attempt so a retry cannot leave two copies. A 100 MB upload does fail on its own: publishing 1.2.0 got "invalid username, password or token" on the second package while the first had just gone up with the same token, and the same command succeeded immediately afterwards.

Package names contain a space — WarpEngine Client-1.5.0-arm64.dmg — so the list of files is passed one path per line rather than as one string; splitting it on whitespace is what broke the first attempt at publishing 1.1.0.

It needs tea installed and logged in — the devarea repo has make tea for that. Overridable: TAG, REPO, TEA_LOGIN, NOTES, DIST.

make publish TAG=v1.0.2                 # a tag other than package.json's
scripts/release.sh dist/one-file.dmg    # just one package

Node 22 or newer is needed to install, not to run: Electron's own installer is ESM-only, and older Node cannot require() it. The packaged app carries its own runtime.

npm run uitest runs with its own user-data directory and without the single-instance lock. Otherwise a copy the user already has open swallows the test process, which exits 0 and reads as a pass.

Both test scripts accept a sandbox store instead of the real one, which is how this repository is tested without touching a working installation:

STORE_ROOT=/tmp/sandbox-root npm start
SMOKE_HOME=/tmp/sandbox-root/ttg-desktop npm run smoke

How it is put together

TypeScript, in layers, with the dependency rule pointing inward. STRUCTURE.md is the map — the layers, every pattern in use, and the naming rules. The short version:

Layer	What lives there
src/shared/	the IPC channel table, the bridge contract, the DTOs, the two message bundles
src/domain/	models, ports and errors — no Electron, no Node
src/application/	services and the domain → DTO mappers
src/infrastructure/	the adapters: the store engine, HTTP, the archive reader, the filesystem, Electron itself
src/main/	the window, the IPC controllers, the composition root, the self-test
src/preload/	the bridge, bundled into one file — a sandboxed preload cannot require modules
src/renderer/	the state store, the views and the renderer controllers
src/scripts/	the smoke test: the same services with no window at all
scripts/release.sh	creates the Gitea release and replaces its attachments
scripts/after-pack.js	ad-hoc signs the macOS bundle during packaging
scripts/build-assets.mjs	bundles the preload and the renderer, copies the page

Two properties are worth stating because they are what the layers buy:

• The catalog can be driven without a window. make smoke assembles the same services against the same ports with no Electron in the process at all.
• The window never receives a filesystem path. A GameDto carries no paths; the window asks to launch a title by name and the main process resolves what that means from the store's own state.

contextIsolation is on, nodeIntegration off, sandbox on, and the page carries a CSP that allows only its own script and stylesheet plus images over HTTPS. Links open in the real browser; the window itself never navigates.

NativeStoreCatalogGateway is the engine behind the StoreCatalogGateway port, and src/infrastructure/engine/ is the engine itself: the catalog client, the release picker, the host match, the payload installer, the three launcher writers and the state file. Above the port nothing knows any of that exists, which is the point — a second host would be a second gateway, not a second code path.

STORE_ENGINES has one entry today. A RetroArch store writes playlists rather than menu entries, so it would be an entry there and a gateway of its own.

Reading a zip without a dependency

Node has no zip reader and this application has no runtime dependencies, so src/infrastructure/archive/ZipArchive.ts is one over node:zlib — about 150 lines that walk the central directory, inflate stored and deflate entries, and restore the executable bit from each entry's external attributes. That last part is not a detail: the archive records it, and without it nothing the store installs can start.

It reads what our own release pipeline produces and refuses the rest: a zip64 archive, an unknown compression method and a path that would escape the destination are all errors rather than best guesses.

Which WarpEngine served the catalog

Every WarpEngine API response carries a WarpEngine-Version header, so the client knows the engine's age without asking. SUPPORTED_WARP_ENGINE_VERSIONS lists the versions this client is written against, and selectCatalogDialect maps each one to the CatalogDialect that reads its catalog shape.

The switch over that list is exhaustive, which is the whole mechanism: adding a version to the array stops the build — in the type checker and in the linter — until somebody says what it reads like. A new engine version cannot arrive silently.

What the header says	What happens
a supported version	its dialect reads the catalog, and the log names it
nothing at all	read as the oldest supported version, which is what an engine older than 0.4.0 is
older than anything supported	the same, and the log says so
newer than anything supported	the newest dialect is tried anyway, with a warning that titles may be missed

Three versions share one dialect today, because the catalog's shape has not changed across them. One class serving three versions is the honest way to say that.

Verified, and not

The pipeline's commands were run in the same containers it uses, before the pipeline was committed: electronuserland/builder:22 installs, type-checks, lints, passes the smoke test (registry reached, store skipped as it should be on a machine that has none) and produces the AppImage (128 MB) and the deb (100 MB). The Wine step could not be rehearsed here — see above — and the size check that guards it was tested against both outcomes: it rejects the 162 KB stub the failed Wine build left and accepts the two real Linux packages.

A store with no repository was installed end to end from a local registry serving one record with storeRepositoryUrl: null: the id came out as teletypegames, the engine and the shared core downloaded, the written config had the three sections, engine 1.1.0 accepted it, and it listed the same ten titles the configured store does — then a hosted title synced into a sandbox and its menu entry appeared. The setup gate was also photographed on a machine with no store at all.

The 1.3.0 refactor was measured rather than trusted: make check is clean — no type errors, no lint findings, both test suites green — the window was photographed before and after and the two are the same picture, and the packaged 1.3.0 bundle was run from dist/ and drove the real store. The published package contains build/ and package.json and nothing else: 111 entries, no sources, no toolchain.

Exercised on macOS (arm64), with the packaged app from the release rather than a dev run: the store is discovered, the catalog lists, a sync installs, the window renders the installed state, and npm run uitest passes with the grid rendered and both languages in the picker. The bootstrap download was run into an empty directory and the resulting store answered the bridge.

The grid was checked by looking at it, not only by counting nodes: SELFTEST_SHOT has the window capture itself, which is how the collapsed rows were found — the DOM had ten cards and twenty buttons all along, and every count passed while the page showed neither art nor buttons. A screenshot from outside the app is not available here, so the window takes its own.

The side menu was measured with two stores in one root — a sandbox copy alongside the real install — and npm run uitest clicks the store that is not open and checks that the bar, the grid and the categories follow. With a single store the switch is skipped, which is what the normal run reports.

The registry path was exercised against a local endpoint serving the same payload the site returns, with two records: one store whose repository has a config.json and one without. Both installed, and the engine listed all ten titles with the synthesised config. npm run uitest was run twice — with a store present it shows the grid, with none it shows the setup gate and its picker carries both names — and once more with the registry unreachable, which produces the retry gate.

The signing was measured rather than assumed, by setting the quarantine flag on a copy unzipped from the release artifact: codesign --verify --deep --strict is clean, and syspolicy_check reports only the expected "adhoc signed" warning. A quarantined copy is still stopped until it is approved — that part is Gatekeeper policy, not a fault in the package.

Not tried on Linux or Windows. The paths and the launch behaviour are written for them, and the store CLI itself has the same gap — .desktop and .lnk launchers have been generated and read, but nobody has clicked one.