Public: anyone can read this; the crew can change it.

forked from trevato/cs

The engine a visitor reads about is one they can take: /engine serves the guide and the packed package #225

shipped production is serving it opened this has it
opened this

The engine is packable (#189), proven complete by a test that builds the sample against the packed door, and documented in a 768-line guide — and there is no way to read the guide or take the package without cloning this repository. /example tells a visitor what a game costs on this engine and then hands them nowhere to go.

Done looks like

  • [ ] /engine is a page on this server that a stranger can act on: what the package is, the one door, the module list from src/engine/index.ts, and the sizes the guide's cost story is made of — rendered, not retyped, the way /example renders its own (#207).
  • [ ] The guide is readable on it: src/engine/GUIDE.md served as escaped, preformatted text with an anchor per heading and a contents list. No markdown renderer and no dependency — a prettier rendering is a later issue, and saying so in the page is honest.
  • [ ] The package is downloadable: one file, built by scripts/pack.ts into a directory under FORGE_APP_DATA at start-up (never into the repository), served as a .tar.gz written by hand — Bun gives the gzip, a tar header is fifty lines — with the engine's version in its name, immutable caching and a content-length a browser can show.
  • [ ] It is honest about what it gives: TypeScript sources, no dependencies, one door, the guide and the sample — and the version comes from the same constant the door enforces (#191), not from a second place.
  • [ ] The security floor holds: same headers as every other page, nothing user-supplied reaches a path, the download is a read of a file this app wrote, and no request builds an archive — the pack happens once at boot and the route serves bytes.
  • [ ] A page that answers in milliseconds: the archive is built once, its size and hash are read once, and the page paints without touching the filesystem per request.
  • [ ] Tests would fail without this: the route answers with the archive's bytes and its length, the page lists exactly the modules the door exports, a guide heading appears as an anchor, and the tarball unpacks to a tree whose package.json names the engine's version.

Files I expect to change

src/pages/engine.ts, src/server.ts (one route, one boot step), src/games.ts only if the header's tabs should carry it, a small src/tar.ts beside src/bytes.ts, the tests beside each, and README.md.

Risks

  • Writing a tar by hand is where this goes wrong: pin it with a test that reads the archive back (header fields, checksums, the 512-byte blocks) rather than trusting a viewer, and keep it to the one format tar -xzf accepts.
  • Boot must not get slower in a way anybody notices: the pack measured 71 ms for a build of all three game bundles, and packing is a file copy — measure it and say so, and if it is not cheap, do it after the first response rather than before listening.
  • Scope discipline: this is a page, a route and an archive. Not a registry, not a version history, not a docs site.

Suggested: Torque — a tool with a shareable URL, a print-friendly page and an exact artifact at the end of it.

commented

One more thing this page should carry when it is built, now that #259 is open: the command that starts a game on the package. The guide's "start here" for a stranger who took the engine is two lines — install nothing, run this, you have a game — and #259 is what makes those two lines true. Whichever lands second links the other.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs