feat(monitor): add /monitor/usage health check endpoint (#510)

* fix(baseline): add .ts extension to update.worker import

Matches the pattern used by xref and caniuse update routes.
Without the extension, TypeScript cannot resolve the module.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(monitor): add /monitor/usage health check endpoint

Returns name, version, uptime, heapUsed, and heapTotal for the
W3C monitoring dashboard at w3.org/2020/12/express-monitor.

Closes #190

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(monitor): wrap package.json read in try-catch

Prevents a startup crash if package.json is absent in a stripped
build artifact. Falls back to version "unknown".

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(monitor): add Cache-Control, log errors, validate version, add tests

Set Cache-Control: no-store to prevent CDN caching stale health data.
Log package.json read errors instead of silently swallowing. Validate
version is a non-empty string before using it. Add 5 unit tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: marcoscaceres

app.ts

@@ -15,6 +15,7 @@ import respecRouter from "./routes/respec/index.js";
 import w3cRouter from "./routes/w3c/index.js";
 import baselineRouter from "./routes/api/baseline/index.js";
 import wellKnownRouter from "./routes/well-known/index.js";
+import monitorRouter from "./routes/monitor/index.js";
 import docsRouter from "./routes/docs/index.js";
 
 const app = express();
@@ -51,6 +52,7 @@ app.use("/github/:org/:repo", githubRouter);
 app.use("/respec", respecRouter);
 app.use("/w3c", w3cRouter);
 app.use("/.well-known", wellKnownRouter);
+app.use("/monitor", monitorRouter);
 app.use("/docs", docsRouter);
 app.get("/", (_req, res) => res.redirect("/docs/"));
 

routes/monitor/index.ts

@@ -0,0 +1,8 @@
+import { Router } from "express";
+
+import usageRoute from "./usage.js";
+
+const monitor = Router();
+monitor.get("/usage", usageRoute);
+
+export default monitor;

routes/monitor/usage.ts

@@ -0,0 +1,29 @@
+import { Request, Response } from "express";
+import { readFileSync } from "fs";
+import path from "path";
+
+import { PROJECT_ROOT } from "../../utils/constants.js";
+
+let version = "unknown";
+try {
+  const pkg = JSON.parse(
+    readFileSync(path.join(PROJECT_ROOT, "package.json"), "utf-8"),
+  );
+  if (typeof pkg.version === "string" && pkg.version) {
+    version = pkg.version;
+  }
+} catch (error) {
+  console.error("Failed to read version from package.json:", error);
+}
+
+export default function route(_req: Request, res: Response) {
+  const { heapUsed, heapTotal } = process.memoryUsage();
+  res.set("Cache-Control", "no-store");
+  res.json({
+    name: "respec.org",
+    version,
+    uptime: process.uptime(),
+    heapUsed,
+    heapTotal,
+  });
+}

tests/routes/monitor/usage.test.js

@@ -0,0 +1,54 @@
+const { default: route } = await import(
+  "../../../build/routes/monitor/usage.js"
+);
+
+function mockRes() {
+  const res = {
+    _status: 200,
+    _body: undefined,
+    _headers: {},
+    status(code) { res._status = code; return res; },
+    json(body) { res._body = body; return res; },
+    set(header, value) { res._headers[header] = value; return res; },
+  };
+  return res;
+}
+
+describe("monitor/usage", () => {
+  it("returns all required fields with correct types", () => {
+    const res = mockRes();
+    route({}, res);
+    expect(res._body).toBeDefined();
+    expect(typeof res._body.name).toBe("string");
+    expect(typeof res._body.version).toBe("string");
+    expect(typeof res._body.uptime).toBe("number");
+    expect(typeof res._body.heapUsed).toBe("number");
+    expect(typeof res._body.heapTotal).toBe("number");
+  });
+
+  it("returns respec.org as the service name", () => {
+    const res = mockRes();
+    route({}, res);
+    expect(res._body.name).toBe("respec.org");
+  });
+
+  it("sets Cache-Control to no-store", () => {
+    const res = mockRes();
+    route({}, res);
+    expect(res._headers["Cache-Control"]).toBe("no-store");
+  });
+
+  it("returns positive uptime", () => {
+    const res = mockRes();
+    route({}, res);
+    expect(res._body.uptime).toBeGreaterThan(0);
+  });
+
+  it("returns positive heap values", () => {
+    const res = mockRes();
+    route({}, res);
+    expect(res._body.heapUsed).toBeGreaterThan(0);
+    expect(res._body.heapTotal).toBeGreaterThan(0);
+    expect(res._body.heapTotal).toBeGreaterThanOrEqual(res._body.heapUsed);
+  });
+});