Imported from xIGBClutchIx/queryhost (
AGENTS.md). Install upstream withnpx skills add xIGBClutchIx/queryhost. Copyright stays with the author.
Working in QueryHost
This repository contains the TypeScript query library. The hosted API and website are separate projects and must consume the library through its public contract.
Scope
- Implement the current slice completely before expanding the product surface.
- Do not add hosted-service concerns such as accounts, billing, persistent caching, or deployment code here.
- Do not add Cloudflare or Railway dependencies. The library performs live queries and stays portable across Node.js hosts.
- Do not preserve obsolete APIs, compatibility shims, or legacy libraries.
- Keep package-root exports intentional. A module under
src/is not public unlesssrc/index.tsexports it.
Code rules
- Keep TypeScript strict in source, tests, type tests, and scripts.
- Do not use explicit
anyorunknown. Validate external data at the boundary and return a concrete type. - Preserve the distinction between an omitted value and a confirmed empty, zero, or
falsevalue. - Keep network work bounded by a deadline, cancellation signal, byte/count limits, and deterministic cleanup.
- Connect only to addresses returned by the validated, pinned-target pipeline. Do not resolve again inside a transport.
- Convert implementation failures into stable public error contracts; do not expose arbitrary exceptions.
Architecture
Dependencies flow from game profiles to protocol implementations to bounded transports and validated targets. Transports do not interpret games, parsers do not perform network I/O, and shared protocols do not branch on game IDs.
GAME_REGISTRY is the single source of game metadata. Add a game's data contract, GameDataMap entry, registry definition, runtime tests, and type tests together.
See docs/Internals.md for module ownership and detailed invariants. Put durable implementation detail there instead of growing this file.
Documentation
- Keep
README.mdfocused on users: purpose, current capabilities, public contract, setup, and project status. - Document exported APIs with TSDoc.
- Use inline comments for rationale, security boundaries, and non-obvious invariants—not line-by-line narration.
- Update the narrowest relevant document when behavior changes; avoid copying the same explanation into multiple files.
Finish gate
Run the complete repository check before handing off or committing:
npm run verify
Add focused regression tests with every behavior change. Do not commit generated dist/ output or publish/push unless explicitly requested.
Use the repository's conventional, imperative commit subjects. When a commit needs supporting detail, format its body as a concise - list with one meaningful change per item; omit the body when the subject is sufficient.
