@better-forge/runtime 0.0.0-stage → 0.1.1

package/dist/updateCheck.js

@@ -0,0 +1,95 @@
+const REFRESH_MS = 6 * 60 * 60 * 1000;
+const RETRY_MS = 5 * 60 * 1000;
+const TIMEOUT_MS = 5_000;
+/** `UPDATE_CHECK=false` keeps the instance from contacting GitHub (air-gapped or privacy-minded installs). */
+export function updateCheckEnabled(environment = process.env) {
+    return environment.UPDATE_CHECK?.trim().toLowerCase() !== 'false';
+}
+function parseVersion(value) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(value.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+/** True when `candidate` is a higher x.y.z than `current`; false when either is not a plain release version. */
+export function isNewerVersion(candidate, current) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+/**
+ * Asks GitHub which release of `repository` ("owner/name") is newest and remembers it, to point out an update to
+ * whoever runs an older `version()`. All state is in the returned closure.
+ */
+export function createUpdateCheck(options) {
+    const RELEASES_API = `https://api.github.com/repos/${options.repository}/releases/latest`;
+    const resolveAppVersion = options.version;
+    let latest = null;
+    let timer;
+    /** Bumped by every start and stop, so a check still in flight when the service stops cannot schedule another. */
+    let generation = 0;
+    /** The newest published release, null when there is none a user should be pointed at; throws when GitHub cannot be asked. */
+    async function fetchLatestRelease() {
+        const response = await fetch(RELEASES_API, {
+            headers: { Accept: 'application/vnd.github+json', 'User-Agent': `${options.name}/${resolveAppVersion()}` },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw new Error(`GitHub answered ${response.status}`);
+        const body = await response.json();
+        if (typeof body !== 'object' || body === null)
+            return null;
+        const { tag_name: tag, html_url: url, draft, prerelease } = body;
+        if (typeof tag !== 'string' || typeof url !== 'string' || draft === true || prerelease === true)
+            return null;
+        if (!parseVersion(tag) || !url.startsWith(`https://github.com/${options.repository}/`))
+            return null;
+        return { version: tag.replace(/^v/, ''), url };
+    }
+    /** Asks GitHub once and remembers the answer; true when it could be asked. Never throws. */
+    async function checkForUpdate() {
+        try {
+            latest = await fetchLatestRelease();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Checks now, in the background, then every few hours (sooner after a failure). A no-op when `UPDATE_CHECK=false`. */
+    function startUpdateCheck() {
+        stopUpdateCheck();
+        if (!updateCheckEnabled())
+            return;
+        const mine = generation;
+        const run = async () => {
+            const asked = await checkForUpdate();
+            if (mine !== generation)
+                return;
+            timer = setTimeout(() => void run(), asked ? REFRESH_MS : RETRY_MS);
+            timer.unref();
+        };
+        void run();
+    }
+    function stopUpdateCheck() {
+        generation++;
+        clearTimeout(timer);
+        timer = undefined;
+    }
+    /** The newest release when it is newer than the running version, else null. Reads what the background check found. */
+    function getAvailableUpdate() {
+        if (!updateCheckEnabled() || !latest)
+            return null;
+        return isNewerVersion(latest.version, resolveAppVersion()) ? latest : null;
+    }
+    function resetUpdateCheck() {
+        stopUpdateCheck();
+        latest = null;
+    }
+    return { checkForUpdate, startUpdateCheck, stopUpdateCheck, getAvailableUpdate, resetUpdateCheck };
+}
+//# sourceMappingURL=updateCheck.js.map

package/dist/updateCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateCheck.js","sourceRoot":"","sources":["../src/updateCheck.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/** The running version: the `APP_VERSION` environment variable (set by the image build), else the version in the package. */
+export declare function resolveAppVersion(packageVersion: string, environment?: {
+    APP_VERSION?: string | undefined;
+}): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6HAA6H;AAC7H,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,WAAW,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAgB,GAC9D,MAAM,CAER"}

package/dist/version.js

@@ -0,0 +1,5 @@
+/** The running version: the `APP_VERSION` environment variable (set by the image build), else the version in the package. */
+export function resolveAppVersion(packageVersion, environment = process.env) {
+    return environment.APP_VERSION?.trim() || packageVersion;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6HAA6H;AAC7H,MAAM,UAAU,iBAAiB,CAC/B,cAAsB,EACtB,cAAoD,OAAO,CAAC,GAAG;IAE/D,OAAO,WAAW,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,cAAc,CAAA;AAC1D,CAAC"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@better-forge/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Application bootstrap: Fastify defaults, health, shutdown, update check, app lock and SSE.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/runtime#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "peerDependencies": {
+    "@fastify/cookie": "^11.1.1",
+    "@fastify/cors": "^10.0.2",
+    "@fastify/jwt": "^10.1.0",
+    "@fastify/multipart": "^9.0.3",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/static": "^10.1.3",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.3.2"
+  },
+  "devDependencies": {
+    "@fastify/cookie": "^11.1.1",
+    "@fastify/cors": "^10.0.2",
+    "@fastify/jwt": "^10.1.0",
+    "@fastify/multipart": "^9.0.3",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/static": "^10.1.3",
+    "@types/node": "^26.6.2",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.3.2",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@better-forge/db": "0.1.1"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/appLock.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { currentProcessOwner, isOwnerAlive, type ProcessOwner } from './processLiveness.js'
+
+const FRESH_MS = 30_000
+
+/**
+ * A stalled heartbeat (event loop blocked by a long synchronous task) still counts as running
+ * while the recorded pid is alive — but only for this long, so a reused pid cannot block forever.
+ */
+const LIVE_OWNER_MS = 10 * 60_000
+
+/**
+ * The marker file that tells a restore or a second start that the application is running. `name` is how the
+ * application is called in the refusal, `fileName` the marker inside `dir()` (evaluated on each use).
+ */
+export function createAppLock(options: { name: string; fileName: string; dir: () => string }) {
+  const RUNNING_MESSAGE = `${options.name} is still running. Stop the application before restoring.`
+  const lockPath = (): string => path.join(options.dir(), options.fileName)
+
+  function readOwner(file: string): Partial<ProcessOwner> {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<ProcessOwner> }
+    catch { return {} }
+  }
+
+  /** Removes a marker whose owner is gone; throws while the app still looks alive. */
+  function clearStaleMarker(options: { checkOwner: boolean }): void {
+    const file = lockPath()
+    if (!fs.existsSync(file)) return
+    const age = Date.now() - fs.statSync(file).mtimeMs
+    const ownerAlive = isOwnerAlive(readOwner(file))
+    // A killed process (Ctrl+C on Windows, tsx watch restart) leaves a fresh marker; startup trusts a dead pid over the heartbeat.
+    if (age < FRESH_MS && (options.checkOwner || ownerAlive)) throw new Error(RUNNING_MESSAGE)
+    if (options.checkOwner && age < LIVE_OWNER_MS && ownerAlive) throw new Error(RUNNING_MESSAGE)
+    fs.rmSync(file, { force: true })
+  }
+
+  /** Used by restore: also refuses while the recorded app process is alive but its heartbeat has stalled. */
+  function assertAppStopped(): void {
+    clearStaleMarker({ checkOwner: true })
+  }
+
+  /** Startup uses the heartbeat only, so a restart after a crash is never blocked by an unrelated process that reused the pid. */
+  function acquireAppLock(): () => void {
+    clearStaleMarker({ checkOwner: false })
+    fs.mkdirSync(options.dir(), { recursive: true })
+    const file = lockPath()
+    fs.writeFileSync(file, JSON.stringify({ ...currentProcessOwner(), startedAt: Date.now() }), { flag: 'wx', mode: 0o600 })
+    const heartbeat = setInterval(() => {
+      try { fs.utimesSync(file, new Date(), new Date()) } catch { /* shutdown race */ }
+    }, 5_000)
+    heartbeat.unref()
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      clearInterval(heartbeat)
+      fs.rmSync(file, { force: true })
+    }
+  }
+
+  return { assertAppStopped, acquireAppLock }
+}

package/src/createBetterApp.ts

@@ -0,0 +1,236 @@
+import fs from 'node:fs'
+import Fastify, { type FastifyInstance, type FastifyRequest } from 'fastify'
+import cors from '@fastify/cors'
+import cookie from '@fastify/cookie'
+import jwt from '@fastify/jwt'
+import multipart from '@fastify/multipart'
+import rateLimit from '@fastify/rate-limit'
+import { rateLimitKey } from './rateLimitKey.js'
+import staticFiles from '@fastify/static'
+import { errorHandler } from './errorHandler.js'
+import { redactUrl } from './redactUrl.js'
+import { resolveTrustProxy } from './proxy.js'
+import { createRuntimeShutdown } from './shutdown.js'
+
+const DEFAULT_JWT_SECRET = 'dev-secret-change-me'
+const EXAMPLE_SECRETS = new Set([
+  'change-me-to-a-long-random-string',
+  'change-me-to-a-64-char-hex-string',
+])
+
+/** How long a signed-in session token lives. */
+export const JWT_EXPIRES_IN = '12h'
+
+/** The secret sessions are signed with: from `JWT_SECRET`, which production insists on being a real one. */
+export function resolveJwtSecret(env: NodeJS.ProcessEnv = process.env): string {
+  const secret = env['JWT_SECRET']
+  if (env['NODE_ENV'] !== 'production') {
+    if (!secret) console.warn('JWT_SECRET not set - using insecure default (development only)')
+    return secret ?? DEFAULT_JWT_SECRET
+  }
+  if (!secret || secret.length < 32 || EXAMPLE_SECRETS.has(secret)) {
+    throw new Error('JWT_SECRET must be set to a non-default value of at least 32 characters in production')
+  }
+  return secret
+}
+
+export interface BetterAppOptions {
+  /** Request URLs are logged with the value of these query parameters replaced (capability tokens in links). */
+  redactQueryParams?: readonly string[]
+  /** Request paths whose next segment is a capability token, for example `/links/` (the token is not logged). */
+  redactPathTokenPrefixes?: readonly string[]
+  /** Checks run before anything is created (for example that the encryption key is usable); throw to refuse to start. */
+  validate?: () => void
+  /** Where uploaded files are kept and served from (`/uploads/`). */
+  uploads: { dir: string; maxFileBytes: number }
+  /** Whether a response to this request may be shown in a frame of our own origin (anything else is refused). */
+  allowSameOriginFraming?: (request: { path: string; query: URLSearchParams }) => boolean
+  /** The database is opened only once the application has been set up. */
+  database: {
+    isReady: () => boolean
+    open: () => void
+    migrate: () => void
+    close: () => void
+  }
+  /** Registers every route of the application. */
+  routes: (app: FastifyInstance) => Promise<void>
+  /** Registers the built front-ends; called in production only, after the routes. */
+  frontends?: (app: FastifyInstance) => Promise<void>
+  /** Takes the lock that keeps a second instance away from the data directory; returns the release. */
+  acquireLock: () => () => void
+  /** Work that runs only while the application is set up. */
+  backgroundServices?: {
+    start: () => void
+    stop: () => void
+    /** Resolves once the work `stop` left running has finished; the shutdown waits for it until its deadline. */
+    drain?: () => Promise<void>
+  }
+  /** Called when the process is asked to stop, before the server drains (close event streams, say). */
+  stopIntake?: () => void
+  /** How long a stop waits for the server and the background work to drain before it exits anyway. Default 5 seconds. */
+  shutdownDeadlineMs?: number
+  /** Name used in the line logged when the server is up. */
+  logName?: string
+  port?: number
+}
+
+/**
+ * Builds the HTTP application the Better products share: logging that hides credentials, proxy trust, CORS and a
+ * cross-site guard, cookies, JWT sessions, rate limiting, uploads, security headers, the database once set up, and the
+ * application's routes. `run` then takes the lock, listens, and wires the shutdown that closes everything in order.
+ */
+export async function createBetterApp(options: BetterAppOptions) {
+  const redaction = { queryParams: options.redactQueryParams, pathTokenPrefixes: options.redactPathTokenPrefixes }
+
+  const app = Fastify({
+    logger: {
+      level: 'info',
+      redact: {
+        paths: ['req.headers.authorization', 'req.headers.cookie', 'res.headers["set-cookie"]'],
+        censor: '[redacted]',
+      },
+      serializers: {
+        req: (req) => ({
+          method: req.method,
+          url: redactUrl(req.url, redaction),
+          host: req.host,
+          remoteAddress: req.ip,
+          ...(req.socket?.remotePort !== undefined ? { remotePort: req.socket.remotePort } : {}),
+        }),
+      },
+    },
+    trustProxy: resolveTrustProxy(),
+  })
+
+  app.setErrorHandler(errorHandler)
+
+  // CORS
+  const allowedOrigins = process.env['ALLOWED_ORIGINS']?.split(',').map((o) => o.trim())
+  await app.register(cors, {
+    origin: allowedOrigins
+      ?? (process.env['NODE_ENV'] === 'production' ? false : true),
+    credentials: true,
+  })
+
+  await app.register(cookie)
+
+  // Reject unsafe cross-site browser requests before they reach auth or setup routes.
+  app.addHook('onRequest', async (req, reply) => {
+    if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) return
+    if (process.env['NODE_ENV'] !== 'production') return
+    if (req.headers['sec-fetch-site'] === 'cross-site') {
+      return reply.code(403).send({ error: 'Cross-site request rejected' })
+    }
+    const origin = req.headers.origin
+    if (!origin) return
+    const ownOrigin = `${req.protocol}://${req.headers.host}`
+    if (origin !== ownOrigin && !allowedOrigins?.includes(origin)) {
+      return reply.code(403).send({ error: 'Origin not allowed' })
+    }
+  })
+
+  // JWT
+  const jwtSecret = resolveJwtSecret()
+  options.validate?.()
+  await app.register(jwt, {
+    secret: jwtSecret,
+    sign: { expiresIn: JWT_EXPIRES_IN },
+  })
+
+  // Rate limiting (applied per-route where needed); IPv6 clients are counted per /64
+  await app.register(rateLimit, { global: false, keyGenerator: (req) => rateLimitKey(req.ip) })
+
+  // Multipart (file uploads)
+  await app.register(multipart, {
+    limits: { fileSize: options.uploads.maxFileBytes },
+  })
+
+  // Serve uploaded files
+  if (!fs.existsSync(options.uploads.dir)) {
+    fs.mkdirSync(options.uploads.dir, { recursive: true })
+  }
+  await app.register(staticFiles, {
+    root: options.uploads.dir,
+    prefix: '/uploads/',
+    decorateReply: false,
+  })
+
+  // Security headers
+  app.addHook('onSend', (req: FastifyRequest, reply, _payload, done) => {
+    const [requestPath = '', query = ''] = req.url.split('?', 2)
+    const framed = options.allowSameOriginFraming?.({ path: requestPath, query: new URLSearchParams(query) }) ?? false
+    reply.header('X-Content-Type-Options', 'nosniff')
+    reply.header('X-Frame-Options', framed ? 'SAMEORIGIN' : 'DENY')
+    reply.header('Referrer-Policy', 'strict-origin-when-cross-origin')
+    reply.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()')
+    reply.header('Cross-Origin-Opener-Policy', 'same-origin')
+    reply.header('Content-Security-Policy', [
+      "default-src 'self'",
+      "base-uri 'self'",
+      "object-src 'none'",
+      framed ? "frame-ancestors 'self'" : "frame-ancestors 'none'",
+      "form-action 'self'",
+      "script-src 'self'",
+      "style-src 'self' 'unsafe-inline'",
+      "font-src 'self'",
+      "img-src 'self' data: blob:",
+      "connect-src 'self'",
+    ].join('; '))
+    if (process.env['NODE_ENV'] === 'production') {
+      reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+    }
+    done()
+  })
+
+  // Initialize DB only when setup has been completed
+  if (options.database.isReady()) {
+    options.database.open()
+    options.database.migrate()
+  }
+
+  await options.routes(app)
+
+  // Serve built frontend apps in production
+  if (process.env['NODE_ENV'] === 'production') await options.frontends?.(app)
+
+  /** Takes the lock, listens, and makes the process stop cleanly on SIGTERM and SIGINT. */
+  async function run(): Promise<void> {
+    const port = options.port ?? Number(process.env['PORT'] ?? 3000)
+    const releaseLock = options.acquireLock()
+    const runtime = createRuntimeShutdown({
+      stopIntake: () => {
+        options.stopIntake?.()
+        options.backgroundServices?.stop()
+      },
+      closeServer: () => app.close(),
+      ...(options.backgroundServices?.drain ? { drain: options.backgroundServices.drain } : {}),
+      ...(options.shutdownDeadlineMs !== undefined ? { forceExitMs: options.shutdownDeadlineMs } : {}),
+      releaseResources: () => {
+        options.database.close()
+        releaseLock()
+      },
+      exit: (code) => process.exit(code),
+    })
+    // onClose runs after the HTTP server has drained, so the DB is no longer in use.
+    app.addHook('onClose', async () => {
+      runtime.cleanup()
+    })
+    try {
+      await app.listen({ port, host: '0.0.0.0' })
+    } catch (error) {
+      runtime.cleanup()
+      throw error
+    }
+    console.log(`✓ ${options.logName ?? 'API'} running on http://localhost:${port}`)
+
+    for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+      process.once(signal, runtime.shutdown)
+    }
+
+    if (options.database.isReady()) options.backgroundServices?.start()
+  }
+
+  return { app, run }
+}
+
+export type BetterApp = Awaited<ReturnType<typeof createBetterApp>>

package/src/dataPaths.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+type Env = NodeJS.ProcessEnv
+
+/** Where the application keeps its data: `DATA_DIR`, else `./data` under the working directory. */
+export function dataDir(env: Env = process.env): string {
+  return path.resolve(env['DATA_DIR'] ?? path.join(process.cwd(), 'data'))
+}
+
+/** The SQLite file: `DATABASE_PATH`, else `db.sqlite` in the data directory. */
+export function databasePath(env: Env = process.env): string {
+  return path.resolve(env['DATABASE_PATH'] ?? path.join(dataDir(env), 'db.sqlite'))
+}
+
+/** The file that records the first-run setup was completed: `SETUP_CONFIG_PATH`, else `setup.json` in the data directory. */
+export function setupConfigPath(env: Env = process.env): string {
+  return path.resolve(env['SETUP_CONFIG_PATH'] ?? path.join(dataDir(env), 'setup.json'))
+}
+
+/** Where backups are written: `BACKUP_DIR`, else `backups` in the data directory. */
+export function backupDir(env: Env = process.env): string {
+  return path.resolve(env['BACKUP_DIR'] ?? path.join(dataDir(env), 'backups'))
+}
+
+interface SetupConfig {
+  setupComplete: boolean
+  dbType: 'sqlite'
+}
+
+export function isSetupComplete(env: Env = process.env): boolean {
+  try {
+    const file = setupConfigPath(env)
+    if (!fs.existsSync(file)) return false
+    const cfg = JSON.parse(fs.readFileSync(file, 'utf-8')) as SetupConfig
+    return cfg.setupComplete === true
+  } catch {
+    // A marker that exists but cannot be read is not a fresh install: refuse setup rather than reopen it.
+    return true
+  }
+}
+
+export function writeSetupComplete(dbType: 'sqlite' = 'sqlite', env: Env = process.env): void {
+  const file = setupConfigPath(env)
+  const dir = path.dirname(file)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(file, JSON.stringify({ setupComplete: true, dbType }, null, 2))
+}

package/src/errorHandler.ts

@@ -0,0 +1,15 @@
+import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify'
+
+/**
+ * Unexpected failures are logged in full but never echoed to the client: driver errors carry the
+ * SQL and its parameters, which can include encrypted secrets. Client errors (4xx) keep their
+ * message in the `{ error }` shape the admin and status clients read.
+ */
+export function errorHandler(error: FastifyError, req: FastifyRequest, reply: FastifyReply) {
+  const statusCode = error.statusCode && error.statusCode >= 400 ? error.statusCode : 500
+  if (statusCode >= 500) {
+    req.log.error({ err: error }, 'Unhandled request error')
+    return reply.code(statusCode).send({ error: 'Internal Server Error' })
+  }
+  return reply.code(statusCode).send({ error: error.message })
+}

package/src/health.ts

@@ -0,0 +1,109 @@
+import type { FastifyInstance } from 'fastify'
+import { sql } from 'drizzle-orm'
+import type { SqliteDatabase } from '@better-forge/db'
+import type { LatestRelease } from './updateCheck.js'
+
+/** `GET /health` (the process is up) and `GET /ready` (set up and the database answers), for load balancers and probes. */
+export function createHealthRoutes(options: { db: SqliteDatabase; isSetupComplete: () => boolean }) {
+  return async function healthRoutes(app: FastifyInstance) {
+    app.get('/health', async () => ({ status: 'ok' }))
+
+    app.get('/ready', async (_req, reply) => {
+      if (!options.isSetupComplete()) {
+        return reply.code(503).send({ status: 'not_ready' })
+      }
+      try {
+        await options.db.run(sql`SELECT 1`)
+        return { status: 'ready' }
+      } catch {
+        return reply.code(503).send({ status: 'not_ready' })
+      }
+    })
+  }
+}
+
+export type ComponentStatus = 'ok' | 'attention' | 'error' | 'disabled'
+
+/** One part of the system the report describes. Its `status` is what the overall status is decided by. */
+export type HealthSection = { status: ComponentStatus } & Record<string, unknown>
+
+export interface HealthContributor {
+  /** The key of the section in the report. */
+  key: string
+  /**
+   * When true, a section in the `error` status makes the whole report `degraded`; otherwise it is only shown.
+   */
+  critical: boolean
+  /** Builds the section. Called after the database was probed; `now` is the time the report is made for. */
+  collect(context: { now: number; databaseOk: boolean }): Promise<HealthSection> | HealthSection
+}
+
+export interface SystemHealthReport {
+  status: 'healthy' | 'degraded'
+  generatedAt: number
+  application: {
+    status: 'ok'
+    version: string
+    uptimeSeconds: number
+    /** A newer published release, or null when up to date, unknown or the update check is off. */
+    update: LatestRelease | null
+  }
+  database: {
+    status: 'ok' | 'error'
+    responseMs: number | null
+  }
+  /** The sections of the contributors, by key. */
+  [section: string]: unknown
+}
+
+/**
+ * The protected report of how the instance is doing: the process, the database, and one section per contributor the
+ * application registers (a scheduler, a queue, backups, ...). Exposes state, not raw errors.
+ */
+export function createSystemHealth(options: {
+  db: SqliteDatabase
+  version: () => string
+  update: () => LatestRelease | null
+  contributors: readonly HealthContributor[]
+}) {
+  async function getSystemHealthReport(now = Date.now()): Promise<SystemHealthReport> {
+    const databaseStartedAt = Date.now()
+    let database: SystemHealthReport['database'] = { status: 'error', responseMs: null }
+    try {
+      await options.db.run(sql`SELECT 1`)
+      database = { status: 'ok', responseMs: Date.now() - databaseStartedAt }
+    } catch {
+      // The protected report deliberately exposes state, not raw database errors.
+    }
+
+    const sections: Record<string, HealthSection> = {}
+    for (const contributor of options.contributors) {
+      sections[contributor.key] = await contributor.collect({ now, databaseOk: database.status === 'ok' })
+    }
+    const failing = options.contributors.some((contributor) => contributor.critical && sections[contributor.key]!.status === 'error')
+
+    return {
+      status: database.status === 'ok' && !failing ? 'healthy' : 'degraded',
+      generatedAt: now,
+      application: { status: 'ok', version: options.version(), uptimeSeconds: Math.floor(process.uptime()), update: options.update() },
+      database,
+      ...sections,
+    }
+  }
+
+  /** Routes: the report at `/` and, at `/update`, only the running version and a newer release, if any. */
+  async function systemHealthRoutes(app: FastifyInstance) {
+    app.get('/', async (_request, reply) => {
+      reply.header('Cache-Control', 'no-store')
+      return getSystemHealthReport()
+    })
+
+    /** Cheap enough for a dashboard to ask on every visit. */
+    app.get('/update', async (_request, reply) => {
+      reply.header('Cache-Control', 'no-store')
+      return { version: options.version(), update: options.update() }
+    })
+  }
+
+  return { getSystemHealthReport, systemHealthRoutes }
+}