Add public shard read endpoints + live SSE stream (phase 2)

Curated, same-origin, token-free reads so the browser never sees the sidecar
URL or token:

- public/shard.controller.js:
  - GET /public/shard/status — connection state + online count + latest economy
    (from the site's ingested data).
  - GET /public/shard/feed?kind=&limit= — recent notable events from the log.
  - GET /public/shard/economy — gold-supply series (oldest → newest).
  - GET /public/shard/idoc — houses currently at IDOC.
  - GET /public/shard/char/:serial — live sheet round-trip via uoLinkClient,
    briefly cached; 503 (shard restarting) serves a stale cache or a retry
    banner rather than an error.
  - GET /public/shard/stream — public SSE channel (safe kinds only).
- Wired into public.routes.js with express-validator guards and #swagger
  annotations; new "Public · Shard" tag + ShardStatus/ShardEvent/
  ShardEconomyPoint/ShardHouse schemas; swagger-output.json regenerated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011qPmpmVH1xGCiZoz9m9vW3

server/src/router/v1/public/shard.controller.js

@@ -0,0 +1,121 @@
+// ── Public: shard live data ────────────────────────────────────────────────
+//
+// Same-origin, token-free read endpoints backed by the data the WS ingest
+// pipeline persists (shard_online / shard_events / shard_economy / shard_houses)
+// plus a live character round-trip to the sidecar. The browser never sees the
+// sidecar URL or token — every sidecar call is server-side (uoLinkClient).
+//
+// The stored-data endpoints are cheap DB reads. The live /char endpoint hits the
+// running shard, so it is briefly cached and degrades gracefully: a 503 (shard
+// restarting) surfaces as a retry-able banner rather than an error.
+
+const shardEvents = require('../../../model/shardEvents/shardEvents.model')
+const shardState = require('../../../model/shardState/shardState.model')
+const uoLinkConfig = require('../../../model/uoLinkConfig/uoLinkConfig.model')
+const uoLinkClient = require('../../../utils/uoLinkClient')
+const broadcast = require('../../../utils/shardBroadcast')
+
+const log = require('../../../utils/logger')('public-shard')
+
+// Serials are opaque hex keys like "0x24C" — validate before hitting the sidecar.
+const SERIAL_RE = /^0x[0-9a-fA-F]+$/
+
+// Tiny in-memory cache for live character sheets (the sidecar warns these hit the
+// live shard, so cache them). Keyed by serial; short TTL.
+const CHAR_TTL_MS = 20000
+const charCache = new Map()
+
+// GET /public/shard/status — connection state + online count + latest economy.
+async function getStatus(req, res) {
+  try {
+    const config = await uoLinkConfig.getSafe()
+    const [online, economy] = await Promise.all([
+      shardState.onlineCount(),
+      shardState.latestEconomy(),
+    ])
+    return res.json({
+      enabled: config.enabled,
+      status: config.status,
+      pluginConnected: config.pluginConnected,
+      lastEventAt: config.lastEventAt,
+      onlineCount: online,
+      economy,
+    })
+  } catch (err) {
+    log.error('shard.getStatus', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/feed?kind=&limit= — recent notable events from the log.
+async function getFeed(req, res) {
+  try {
+    const { kind, limit } = req.query
+    const events = await shardEvents.list({ kind, limit })
+    return res.json(events)
+  } catch (err) {
+    log.error('shard.getFeed', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/economy — gold-supply series, oldest → newest.
+async function getEconomy(req, res) {
+  try {
+    return res.json(await shardState.listEconomy(req.query.limit))
+  } catch (err) {
+    log.error('shard.getEconomy', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/idoc — houses currently in danger (stage IDOC).
+async function getIdoc(req, res) {
+  try {
+    return res.json(await shardState.listIdoc())
+  } catch (err) {
+    log.error('shard.getIdoc', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/char/:serial — live character sheet (cached briefly). A 503
+// from the sidecar means the shard is restarting: report it as such so the UI
+// can show a retry banner instead of an error.
+async function getChar(req, res) {
+  const { serial } = req.params
+  if (!SERIAL_RE.test(serial)) {
+    return res.status(400).json({ message: 'Invalid serial.' })
+  }
+
+  const cached = charCache.get(serial)
+  if (cached && Date.now() - cached.at < CHAR_TTL_MS) {
+    return res.json(cached.data)
+  }
+
+  try {
+    const result = await uoLinkClient.getCharBySerial(serial)
+    if (result.ok) {
+      charCache.set(serial, { at: Date.now(), data: result.data })
+      return res.json(result.data)
+    }
+    if (result.status === 404) return res.status(404).json({ message: 'Character not found.' })
+    if (result.status === 503) {
+      // Serve a stale cache if we have one; otherwise the restart banner.
+      if (cached) return res.json(cached.data)
+      return res.status(503).json({ message: 'The game server is restarting — try again shortly.' })
+    }
+    if (result.status === 0) return res.status(503).json({ message: 'Shard data is unavailable right now.' })
+    return res.status(502).json({ message: 'Could not reach the shard.' })
+  } catch (err) {
+    log.error('shard.getChar', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/stream — public live-event SSE channel (safe kinds only).
+function stream(req, res) {
+  broadcast.subscribe(req, res, 'public')
+}
+
+module.exports = { getStatus, getFeed, getEconomy, getIdoc, getChar, stream }