feat(public): version/health surfacing for the app first-run probe

Expose a small backend identity/version descriptor (§8.4 of the Android plan)
so a client can positively recognize a Runic Gateway backend on first-run and
run a version-mismatch guard, instead of inferring from an incidental shape.

- New config/version.js: { service: 'runic-gateway', api: 'v1', server: <pkg> }.
- GET /public/status now includes a `version` block (the app already calls this
  on first-run, so it gets identity + version in one round trip).
- New GET /public/version: a lightweight, DB-free identity endpoint — the
  canonical target for the version guard and a cheap liveness check.
- Swagger: PublicVersion schema + version on PublicStatus; /version annotated.
- test/publicVersion.test.js covers the config shape and the DB-free 200.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
This commit is contained in:
2026-07-19 11:47:26 -05:00
parent 93a2c0d55f
commit 90c8eae20f
6 changed files with 182 additions and 2 deletions

View File

@@ -0,0 +1,21 @@
// ── Public API version / identity ──────────────────────────────────────────
//
// A tiny, dependency-free descriptor of this backend, surfaced on GET
// /public/status and GET /public/version. A client (notably the Android app)
// uses it to:
// • positively recognize a Runic Gateway backend on first-run (the `service`
// tag), instead of guessing from an incidental response shape; and
// • run a version-mismatch guard — compare `api` against the contract the
// client was built against and surface a clear "update required" state
// rather than mis-parsing a future, changed response.
//
// `api` is the coarse contract version (bumped only on a breaking re-shape, which
// would be a v2 mount); `server` is the informational package version.
const pkg = require('../../package.json')
module.exports = {
service: 'runic-gateway', // stable backend identifier for first-run detection
api: 'v1', // API contract version (matches the /api/v1 mount)
server: pkg.version || '0.0.0', // server package version (informational)
}