@better-forge/runtime 0.1.0 → 0.1.1

package/src/shutdown.ts

@@ -1,62 +1,62 @@
-export interface ShutdownSteps {
-  /** Stops producing new work and ends long-lived streams (SSE) so the server can drain. */
-  stopIntake: () => void
-  /** Stops accepting connections and resolves once in-flight requests have finished. */
-  closeServer: () => Promise<void>
-  /** Resolves once background work that started before the stop (a check about to record its result, say) has finished. */
-  drain?: () => Promise<void>
-  /** Closes the DB and releases the app lock — only safe once no request or background work can still use them. */
-  releaseResources: () => void
-  exit: (code: number) => void
-  forceExitMs?: number
-}
-
-export interface RuntimeShutdown {
-  /** Immediate full teardown, for paths where the server never started or has already closed. */
-  cleanup: () => void
-  /** Signal handler: drain the server and the background work first, then release shared resources and exit. */
-  shutdown: () => void
-}
-
-export function createRuntimeShutdown(steps: ShutdownSteps): RuntimeShutdown {
-  let intakeStopped = false
-  let released = false
-  let shuttingDown = false
-  let forceExit: ReturnType<typeof setTimeout> | undefined
-  const stopIntake = () => {
-    if (intakeStopped) return
-    intakeStopped = true
-    steps.stopIntake()
-  }
-  const release = () => {
-    if (released) return
-    released = true
-    steps.releaseResources()
-  }
-  const cleanup = () => {
-    stopIntake()
-    // A signal-driven shutdown releases after the drain; the server's close hook fires before it.
-    if (!shuttingDown) release()
-  }
-  const finish = (code: number) => {
-    clearTimeout(forceExit)
-    release()
-    steps.exit(code)
-  }
-
-  return {
-    cleanup,
-    shutdown: () => {
-      if (shuttingDown) return
-      shuttingDown = true
-      forceExit = setTimeout(() => {
-        release()
-        steps.exit(1)
-      }, steps.forceExitMs ?? 5_000)
-      forceExit.unref()
-      stopIntake()
-      // The forced exit above is the deadline of the drain: work still running by then is left to the next start.
-      steps.closeServer().then(() => steps.drain?.()).then(() => finish(0), () => finish(1))
-    },
-  }
-}
+export interface ShutdownSteps {
+  /** Stops producing new work and ends long-lived streams (SSE) so the server can drain. */
+  stopIntake: () => void
+  /** Stops accepting connections and resolves once in-flight requests have finished. */
+  closeServer: () => Promise<void>
+  /** Resolves once background work that started before the stop (a check about to record its result, say) has finished. */
+  drain?: () => Promise<void>
+  /** Closes the DB and releases the app lock — only safe once no request or background work can still use them. */
+  releaseResources: () => void
+  exit: (code: number) => void
+  forceExitMs?: number
+}
+
+export interface RuntimeShutdown {
+  /** Immediate full teardown, for paths where the server never started or has already closed. */
+  cleanup: () => void
+  /** Signal handler: drain the server and the background work first, then release shared resources and exit. */
+  shutdown: () => void
+}
+
+export function createRuntimeShutdown(steps: ShutdownSteps): RuntimeShutdown {
+  let intakeStopped = false
+  let released = false
+  let shuttingDown = false
+  let forceExit: ReturnType<typeof setTimeout> | undefined
+  const stopIntake = () => {
+    if (intakeStopped) return
+    intakeStopped = true
+    steps.stopIntake()
+  }
+  const release = () => {
+    if (released) return
+    released = true
+    steps.releaseResources()
+  }
+  const cleanup = () => {
+    stopIntake()
+    // A signal-driven shutdown releases after the drain; the server's close hook fires before it.
+    if (!shuttingDown) release()
+  }
+  const finish = (code: number) => {
+    clearTimeout(forceExit)
+    release()
+    steps.exit(code)
+  }
+
+  return {
+    cleanup,
+    shutdown: () => {
+      if (shuttingDown) return
+      shuttingDown = true
+      forceExit = setTimeout(() => {
+        release()
+        steps.exit(1)
+      }, steps.forceExitMs ?? 5_000)
+      forceExit.unref()
+      stopIntake()
+      // The forced exit above is the deadline of the drain: work still running by then is left to the next start.
+      steps.closeServer().then(() => steps.drain?.()).then(() => finish(0), () => finish(1))
+    },
+  }
+}

package/src/sse.ts

@@ -1,154 +1,154 @@
-import type { FastifyReply, FastifyRequest } from 'fastify'
-import { rateLimitKey } from './rateLimitKey.js'
-
-type SseClient = FastifyReply
-
-/**
- * Shapes what one client receives: return the data to send (possibly reduced) or `null` to skip the
- * event. Clients without a filter receive everything as broadcast.
- */
-export type SseFilter = (event: string, data: unknown) => { data: unknown } | null
-
-export interface ClientInfo {
-  filter?: SseFilter | undefined
-  /** Set for signed-in streams, so revoking the session can end them. */
-  session?: { sessionId: string; userId: number } | undefined
-  ip?: string | undefined
-}
-
-export interface SseLimits {
-  /** Open anonymous streams in total; further ones are refused with 429. Signed-in streams are not counted. */
-  maxClients: number
-  /** Open anonymous streams from one address (an IPv6 /64 counts as one); further ones are refused with 429. */
-  maxClientsPerIp: number
-  /** A client with more unsent bytes than this is not reading and gets disconnected. */
-  maxBufferedBytes: number
-}
-
-const DEFAULT_LIMITS: SseLimits = { maxClients: 1000, maxClientsPerIp: 10, maxBufferedBytes: 1024 * 1024 }
-
-export interface EventStreamOptions {
-  filter?: SseFilter
-  session?: { sessionId: string; userId: number } | undefined
-  /** Re-checked with every keep-alive ping; the stream ends once it resolves to false. */
-  stillAllowed?: () => Promise<boolean>
-  pingIntervalMs?: number
-}
-
-/** Live event streams (server-sent events) to browsers, with per-client filters and session-bound streams. All state is in the returned closure. */
-export function createSse(limitOptions: Partial<SseLimits> = {}) {
-  const limits = { ...DEFAULT_LIMITS, ...limitOptions }
-  const clients = new Map<SseClient, ClientInfo>()
-
-  const listeners = new Set<(event: string) => void>()
-
-  function end(client: SseClient) {
-    try { client.raw.end() } catch { /* ignore shutdown races */ }
-    try { client.raw.destroy() } catch { /* ignore shutdown races */ }
-    clients.delete(client)
-  }
-
-  /** Writes to one client and drops it when it cannot keep up, so a stalled reader cannot grow the heap. */
-  function send(client: SseClient, chunk: string) {
-    try {
-      client.raw.write(chunk)
-      if (client.raw.writableLength > limits.maxBufferedBytes) end(client)
-    } catch {
-      clients.delete(client)
-    }
-  }
-
-  const sseService = {
-    add(client: SseClient, info: ClientInfo = {}) {
-      clients.set(client, info)
-    },
-
-    remove(client: SseClient) {
-      clients.delete(client)
-    },
-
-    /** Server-side hook for anything that must react to the same events clients receive. */
-    onBroadcast(listener: (event: string) => void): () => void {
-      listeners.add(listener)
-      return () => { listeners.delete(listener) }
-    },
-
-    broadcast(event: string, data: unknown) {
-      for (const listener of listeners) listener(event)
-      const format = (value: unknown) => `event: ${event}\ndata: ${JSON.stringify(value)}\n\n`
-      const payload = format(data)
-      for (const [client, { filter }] of clients) {
-        const shaped = filter ? filter(event, data) : { data }
-        if (!shaped) continue
-        send(client, shaped.data === data ? payload : format(shaped.data))
-      }
-    },
-
-    /** Ends the signed-in streams whose session matches, e.g. after the session was revoked. */
-    disconnectSessions(match: (session: { sessionId: string; userId: number }) => boolean) {
-      for (const [client, { session }] of clients) {
-        if (session && match(session)) end(client)
-      }
-    },
-
-    /** Ends every stream opened without signing in, e.g. once access is restricted to signed-in users. */
-    disconnectAnonymous() {
-      for (const [client, { session }] of clients) {
-        if (!session) end(client)
-      }
-    },
-
-    closeAll() {
-      for (const client of clients.keys()) end(client)
-    },
-
-    clientCount() {
-      return clients.size
-    },
-  }
-
-  /** Holds the request open as an event stream until the client disconnects or loses access. */
-  async function serveEventStream(req: FastifyRequest, reply: FastifyReply, options: EventStreamOptions = {}): Promise<void> {
-    // Only anonymous streams are limited: a signed-in one is accountable, and counting it would let
-    // visitors fill the budget the admin stream needs.
-    const ip = rateLimitKey(req.ip)
-    if (!options.session) {
-      let total = 0
-      let fromIp = 0
-      for (const client of clients.values()) {
-        if (client.session) continue
-        total++
-        if (client.ip === ip) fromIp++
-      }
-      if (total >= limits.maxClients || fromIp >= limits.maxClientsPerIp) {
-        return reply.code(429).send({ error: 'Too many open event streams' })
-      }
-    }
-
-    reply.raw.setHeader('Content-Type', 'text/event-stream')
-    reply.raw.setHeader('Cache-Control', 'no-cache')
-    reply.raw.setHeader('Connection', 'keep-alive')
-    reply.raw.setHeader('X-Accel-Buffering', 'no')
-    reply.raw.flushHeaders()
-
-    sseService.add(reply, { filter: options.filter, session: options.session, ip })
-    reply.raw.write('event: ping\ndata: {}\n\n')
-
-    const pingInterval = setInterval(() => {
-      void (async () => {
-        if (options.stillAllowed && !(await options.stillAllowed().catch(() => false))) {
-          clearInterval(pingInterval)
-          end(reply)
-          return
-        }
-        send(reply, `event: ping\ndata: ${JSON.stringify({ ts: Date.now() })}\n\n`)
-        if (!clients.has(reply)) clearInterval(pingInterval)
-      })()
-    }, options.pingIntervalMs ?? 30_000)
-
-    req.raw.on('close', () => { clearInterval(pingInterval); sseService.remove(reply) })
-    await new Promise<void>((resolve) => { req.raw.on('close', resolve) })
-  }
-
-  return { sseService, serveEventStream }
-}
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { rateLimitKey } from './rateLimitKey.js'
+
+type SseClient = FastifyReply
+
+/**
+ * Shapes what one client receives: return the data to send (possibly reduced) or `null` to skip the
+ * event. Clients without a filter receive everything as broadcast.
+ */
+export type SseFilter = (event: string, data: unknown) => { data: unknown } | null
+
+export interface ClientInfo {
+  filter?: SseFilter | undefined
+  /** Set for signed-in streams, so revoking the session can end them. */
+  session?: { sessionId: string; userId: number } | undefined
+  ip?: string | undefined
+}
+
+export interface SseLimits {
+  /** Open anonymous streams in total; further ones are refused with 429. Signed-in streams are not counted. */
+  maxClients: number
+  /** Open anonymous streams from one address (an IPv6 /64 counts as one); further ones are refused with 429. */
+  maxClientsPerIp: number
+  /** A client with more unsent bytes than this is not reading and gets disconnected. */
+  maxBufferedBytes: number
+}
+
+const DEFAULT_LIMITS: SseLimits = { maxClients: 1000, maxClientsPerIp: 10, maxBufferedBytes: 1024 * 1024 }
+
+export interface EventStreamOptions {
+  filter?: SseFilter
+  session?: { sessionId: string; userId: number } | undefined
+  /** Re-checked with every keep-alive ping; the stream ends once it resolves to false. */
+  stillAllowed?: () => Promise<boolean>
+  pingIntervalMs?: number
+}
+
+/** Live event streams (server-sent events) to browsers, with per-client filters and session-bound streams. All state is in the returned closure. */
+export function createSse(limitOptions: Partial<SseLimits> = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...limitOptions }
+  const clients = new Map<SseClient, ClientInfo>()
+
+  const listeners = new Set<(event: string) => void>()
+
+  function end(client: SseClient) {
+    try { client.raw.end() } catch { /* ignore shutdown races */ }
+    try { client.raw.destroy() } catch { /* ignore shutdown races */ }
+    clients.delete(client)
+  }
+
+  /** Writes to one client and drops it when it cannot keep up, so a stalled reader cannot grow the heap. */
+  function send(client: SseClient, chunk: string) {
+    try {
+      client.raw.write(chunk)
+      if (client.raw.writableLength > limits.maxBufferedBytes) end(client)
+    } catch {
+      clients.delete(client)
+    }
+  }
+
+  const sseService = {
+    add(client: SseClient, info: ClientInfo = {}) {
+      clients.set(client, info)
+    },
+
+    remove(client: SseClient) {
+      clients.delete(client)
+    },
+
+    /** Server-side hook for anything that must react to the same events clients receive. */
+    onBroadcast(listener: (event: string) => void): () => void {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+
+    broadcast(event: string, data: unknown) {
+      for (const listener of listeners) listener(event)
+      const format = (value: unknown) => `event: ${event}\ndata: ${JSON.stringify(value)}\n\n`
+      const payload = format(data)
+      for (const [client, { filter }] of clients) {
+        const shaped = filter ? filter(event, data) : { data }
+        if (!shaped) continue
+        send(client, shaped.data === data ? payload : format(shaped.data))
+      }
+    },
+
+    /** Ends the signed-in streams whose session matches, e.g. after the session was revoked. */
+    disconnectSessions(match: (session: { sessionId: string; userId: number }) => boolean) {
+      for (const [client, { session }] of clients) {
+        if (session && match(session)) end(client)
+      }
+    },
+
+    /** Ends every stream opened without signing in, e.g. once access is restricted to signed-in users. */
+    disconnectAnonymous() {
+      for (const [client, { session }] of clients) {
+        if (!session) end(client)
+      }
+    },
+
+    closeAll() {
+      for (const client of clients.keys()) end(client)
+    },
+
+    clientCount() {
+      return clients.size
+    },
+  }
+
+  /** Holds the request open as an event stream until the client disconnects or loses access. */
+  async function serveEventStream(req: FastifyRequest, reply: FastifyReply, options: EventStreamOptions = {}): Promise<void> {
+    // Only anonymous streams are limited: a signed-in one is accountable, and counting it would let
+    // visitors fill the budget the admin stream needs.
+    const ip = rateLimitKey(req.ip)
+    if (!options.session) {
+      let total = 0
+      let fromIp = 0
+      for (const client of clients.values()) {
+        if (client.session) continue
+        total++
+        if (client.ip === ip) fromIp++
+      }
+      if (total >= limits.maxClients || fromIp >= limits.maxClientsPerIp) {
+        return reply.code(429).send({ error: 'Too many open event streams' })
+      }
+    }
+
+    reply.raw.setHeader('Content-Type', 'text/event-stream')
+    reply.raw.setHeader('Cache-Control', 'no-cache')
+    reply.raw.setHeader('Connection', 'keep-alive')
+    reply.raw.setHeader('X-Accel-Buffering', 'no')
+    reply.raw.flushHeaders()
+
+    sseService.add(reply, { filter: options.filter, session: options.session, ip })
+    reply.raw.write('event: ping\ndata: {}\n\n')
+
+    const pingInterval = setInterval(() => {
+      void (async () => {
+        if (options.stillAllowed && !(await options.stillAllowed().catch(() => false))) {
+          clearInterval(pingInterval)
+          end(reply)
+          return
+        }
+        send(reply, `event: ping\ndata: ${JSON.stringify({ ts: Date.now() })}\n\n`)
+        if (!clients.has(reply)) clearInterval(pingInterval)
+      })()
+    }, options.pingIntervalMs ?? 30_000)
+
+    req.raw.on('close', () => { clearInterval(pingInterval); sseService.remove(reply) })
+    await new Promise<void>((resolve) => { req.raw.on('close', resolve) })
+  }
+
+  return { sseService, serveEventStream }
+}

package/src/updateCheck.ts

@@ -1,107 +1,107 @@
-
-
-const REFRESH_MS = 6 * 60 * 60 * 1000
-
-const RETRY_MS = 5 * 60 * 1000
-
-const TIMEOUT_MS = 5_000
-
-export interface LatestRelease {
-  version: string
-  url: string
-}
-
-/** `UPDATE_CHECK=false` keeps the instance from contacting GitHub (air-gapped or privacy-minded installs). */
-export function updateCheckEnabled(environment: { UPDATE_CHECK?: string | undefined } = process.env): boolean {
-  return environment.UPDATE_CHECK?.trim().toLowerCase() !== 'false'
-}
-
-function parseVersion(value: string): [number, number, number] | null {
-  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: string, current: string): boolean {
-  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: { name: string; repository: string; version: () => string }) {
-  const RELEASES_API = `https://api.github.com/repos/${options.repository}/releases/latest`
-  const resolveAppVersion = options.version
-
-  let latest: LatestRelease | null = null
-
-  let timer: NodeJS.Timeout | undefined
-
-  /** 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(): Promise<LatestRelease | null> {
-    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: unknown = await response.json()
-    if (typeof body !== 'object' || body === null) return null
-    const { tag_name: tag, html_url: url, draft, prerelease } = body as Record<string, unknown>
-    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(): Promise<boolean> {
-    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(): void {
-    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(): void {
-    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(): LatestRelease | null {
-    if (!updateCheckEnabled() || !latest) return null
-    return isNewerVersion(latest.version, resolveAppVersion()) ? latest : null
-  }
-
-  function resetUpdateCheck(): void {
-    stopUpdateCheck()
-    latest = null
-  }
-
-  return { checkForUpdate, startUpdateCheck, stopUpdateCheck, getAvailableUpdate, resetUpdateCheck }
-}
+
+
+const REFRESH_MS = 6 * 60 * 60 * 1000
+
+const RETRY_MS = 5 * 60 * 1000
+
+const TIMEOUT_MS = 5_000
+
+export interface LatestRelease {
+  version: string
+  url: string
+}
+
+/** `UPDATE_CHECK=false` keeps the instance from contacting GitHub (air-gapped or privacy-minded installs). */
+export function updateCheckEnabled(environment: { UPDATE_CHECK?: string | undefined } = process.env): boolean {
+  return environment.UPDATE_CHECK?.trim().toLowerCase() !== 'false'
+}
+
+function parseVersion(value: string): [number, number, number] | null {
+  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: string, current: string): boolean {
+  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: { name: string; repository: string; version: () => string }) {
+  const RELEASES_API = `https://api.github.com/repos/${options.repository}/releases/latest`
+  const resolveAppVersion = options.version
+
+  let latest: LatestRelease | null = null
+
+  let timer: NodeJS.Timeout | undefined
+
+  /** 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(): Promise<LatestRelease | null> {
+    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: unknown = await response.json()
+    if (typeof body !== 'object' || body === null) return null
+    const { tag_name: tag, html_url: url, draft, prerelease } = body as Record<string, unknown>
+    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(): Promise<boolean> {
+    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(): void {
+    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(): void {
+    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(): LatestRelease | null {
+    if (!updateCheckEnabled() || !latest) return null
+    return isNewerVersion(latest.version, resolveAppVersion()) ? latest : null
+  }
+
+  function resetUpdateCheck(): void {
+    stopUpdateCheck()
+    latest = null
+  }
+
+  return { checkForUpdate, startUpdateCheck, stopUpdateCheck, getAvailableUpdate, resetUpdateCheck }
+}

package/src/version.ts

@@ -1,7 +1,7 @@
-/** The running version: the `APP_VERSION` environment variable (set by the image build), else the version in the package. */
-export function resolveAppVersion(
-  packageVersion: string,
-  environment: { APP_VERSION?: string | undefined } = process.env,
-): string {
-  return environment.APP_VERSION?.trim() || packageVersion
-}
+/** The running version: the `APP_VERSION` environment variable (set by the image build), else the version in the package. */
+export function resolveAppVersion(
+  packageVersion: string,
+  environment: { APP_VERSION?: string | undefined } = process.env,
+): string {
+  return environment.APP_VERSION?.trim() || packageVersion
+}