@open-mercato/shared 0.7.1-develop.7150.1.c1941e0c22 → 0.7.1-develop.7152.1.a69e92f9c9

package/src/lib/dev-runtime/layout.ts

@@ -0,0 +1,39 @@
+import { resolveDevRuntimeServerConfig } from './server'
+import {
+  DEV_RUNTIME_BANNER_META_NAME,
+  DEV_RUNTIME_LOGS_URL_META_NAME,
+  DEV_RUNTIME_TOKEN_META_NAME,
+} from './types'
+
+export type DevRuntimeLayoutMeta = {
+  name: string
+  content: string
+}
+
+export type DevRuntimeLayoutConfig = {
+  enabled: boolean
+  bannerEnabled: boolean
+  meta: DevRuntimeLayoutMeta[]
+}
+
+const DISABLED: DevRuntimeLayoutConfig = { enabled: false, bannerEnabled: false, meta: [] }
+
+/**
+ * Server-side helper for the app layout. It exposes the per-run token to the
+ * local dev browser through dev-only `<meta>` elements without adding a context
+ * provider, and returns nothing at all outside a supervised dev runtime.
+ */
+export function resolveDevRuntimeLayoutConfig(env: NodeJS.ProcessEnv = process.env): DevRuntimeLayoutConfig {
+  const config = resolveDevRuntimeServerConfig(env)
+  if (!config.enabled || !config.token) return DISABLED
+
+  const meta: DevRuntimeLayoutMeta[] = [
+    { name: DEV_RUNTIME_TOKEN_META_NAME, content: config.token },
+    { name: DEV_RUNTIME_BANNER_META_NAME, content: config.bannerEnabled ? '1' : '0' },
+  ]
+
+  const logsUrl = typeof env.OM_DEV_RUNTIME_SPLASH_URL === 'string' ? env.OM_DEV_RUNTIME_SPLASH_URL.trim() : ''
+  if (logsUrl) meta.push({ name: DEV_RUNTIME_LOGS_URL_META_NAME, content: logsUrl })
+
+  return { enabled: true, bannerEnabled: config.bannerEnabled, meta }
+}

package/src/lib/dev-runtime/redaction.ts

@@ -0,0 +1,29 @@
+/**
+ * Mirror of the supervisor-side rules in `scripts/dev-runtime-state.mjs`.
+ * The supervisor re-redacts everything it ingests, but the dev-only app route
+ * writes reports to a local file first, so the same rules must apply here.
+ * `scripts/__tests__/dev-runtime-redaction-parity.test.mjs` keeps the two lists
+ * from drifting.
+ */
+const REDACTION_RULES: Array<[RegExp, string]> = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '***'],
+  [/\b(postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|rediss?|amqps?)::?\/\/[^\s'"`<>)]+/gi, '$1://***'],
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer ***'],
+  [/\b(authorization|proxy-authorization|x-api-key|x-auth-token)(\s*[:=]\s*)(?:\w+\s+)?\S+/gi, '$1$2***'],
+  [/\b(set-cookie|cookie)(\s*[:=]\s*)[^\n]+/gi, '$1$2***'],
+  [/\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]*/g, '***'],
+  [/\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{8,}/g, '***'],
+  [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, '***'],
+  [/\b(password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|session[_-]?id)("?\s*[:=]\s*"?)([^\s"',;)}]+)/gi, '$1$2***'],
+]
+
+export function redactDevRuntimeText(value: unknown, maxLength = 400): string | undefined {
+  if (value == null) return undefined
+  let text = String(value)
+  for (const [pattern, replacement] of REDACTION_RULES) {
+    text = text.replace(pattern, replacement)
+  }
+  text = text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '').replace(/\s+$/g, '')
+  if (!text) return undefined
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}…` : text
+}

package/src/lib/dev-runtime/report.ts

@@ -0,0 +1,116 @@
+import {
+  DEV_RUNTIME_BANNER_META_NAME,
+  DEV_RUNTIME_DIAGNOSTICS_PATH,
+  DEV_RUNTIME_LOGS_URL_META_NAME,
+  DEV_RUNTIME_TOKEN_HEADER,
+  DEV_RUNTIME_TOKEN_META_NAME,
+  type DevRuntimeReport,
+  type DevRuntimeReportKind,
+} from './types'
+
+const MAX_MESSAGE_LENGTH = 500
+const MAX_STACK_LENGTH = 2000
+const MAX_REPORTS_PER_PAGE = 20
+
+let sentReports = 0
+const seenFingerprints = new Set<string>()
+
+function readMeta(name: string): string | null {
+  if (typeof document === 'undefined') return null
+  const element = document.querySelector(`meta[name="${name}"]`)
+  const content = element?.getAttribute('content')?.trim()
+  return content ? content : null
+}
+
+export function readDevRuntimeToken(): string | null {
+  return readMeta(DEV_RUNTIME_TOKEN_META_NAME)
+}
+
+export function isDevRuntimeBannerEnabled(): boolean {
+  return readMeta(DEV_RUNTIME_BANNER_META_NAME) === '1'
+}
+
+export function readDevRuntimeLogsUrl(): string | null {
+  return readMeta(DEV_RUNTIME_LOGS_URL_META_NAME)
+}
+
+function truncate(value: unknown, maxLength: number): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  if (!trimmed) return undefined
+  return trimmed.length > maxLength ? trimmed.slice(0, maxLength) : trimmed
+}
+
+export function describeDevRuntimeError(error: unknown): { message: string; stack?: string; digest?: string } {
+  if (error instanceof Error) {
+    return {
+      message: `${error.name}: ${error.message}`,
+      stack: truncate(error.stack, MAX_STACK_LENGTH),
+      digest: truncate((error as { digest?: unknown }).digest, 64),
+    }
+  }
+  if (typeof error === 'string') return { message: error }
+  return { message: 'Unknown browser error' }
+}
+
+/**
+ * Best-effort, fire-and-forget browser report. It never blocks rendering, never
+ * retries, and silently gives up when the collector is unavailable — a broken
+ * runtime must still show its own rendered error state.
+ */
+export function reportDevRuntimeError(input: {
+  kind: DevRuntimeReportKind
+  error?: unknown
+  message?: string
+  digest?: string
+  stack?: string
+}): void {
+  if (typeof window === 'undefined') return
+  if (sentReports >= MAX_REPORTS_PER_PAGE) return
+
+  const token = readDevRuntimeToken()
+  if (!token) return
+
+  const described: Partial<ReturnType<typeof describeDevRuntimeError>> = input.error !== undefined
+    ? describeDevRuntimeError(input.error)
+    : {}
+  const message = truncate(input.message ?? described.message, MAX_MESSAGE_LENGTH)
+  if (!message) return
+
+  const digest = truncate(input.digest ?? described.digest, 64)
+  const stack = truncate(input.stack ?? described.stack, MAX_STACK_LENGTH)
+  const path = truncate(window.location?.pathname, 300)
+
+  // One report per distinct failure per page: a render loop must not turn into
+  // a request loop.
+  const fingerprint = `${input.kind}|${digest ?? message}|${path ?? ''}`
+  if (seenFingerprints.has(fingerprint)) return
+  seenFingerprints.add(fingerprint)
+  sentReports += 1
+
+  const report: DevRuntimeReport = {
+    kind: input.kind,
+    message,
+    timestamp: new Date().toISOString(),
+  }
+  if (digest) report.digest = digest
+  if (stack) report.stack = stack
+  if (path) report.path = path
+
+  try {
+    void fetch(DEV_RUNTIME_DIAGNOSTICS_PATH, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', [DEV_RUNTIME_TOKEN_HEADER]: token },
+      body: JSON.stringify(report),
+      cache: 'no-store',
+      keepalive: true,
+    }).catch(() => {})
+  } catch {
+    // Reporting is optional; the rendered fallback stays the source of truth.
+  }
+}
+
+export function resetDevRuntimeReporterForTests(): void {
+  sentReports = 0
+  seenFingerprints.clear()
+}

package/src/lib/dev-runtime/routes.ts

@@ -0,0 +1,219 @@
+import { z } from 'zod'
+
+import { redactDevRuntimeText } from './redaction'
+import {
+  appendDevRuntimeActionRequest,
+  appendDevRuntimeReport,
+  isMatchingDevRuntimeToken,
+  readDevRuntimeLogs,
+  readDevRuntimeStatus,
+  resolveDevRuntimeServerConfig,
+  type DevRuntimeServerConfig,
+} from './server'
+import {
+  DEV_RUNTIME_RECOVERY_ACTIONS,
+  DEV_RUNTIME_TOKEN_HEADER,
+  type DevRuntimeReport,
+  type RuntimeRecoveryAction,
+} from './types'
+
+export const MAX_DEV_RUNTIME_REPORT_BYTES = 8192
+const MAX_REPORTS_PER_WINDOW = 30
+const RATE_LIMIT_WINDOW_MS = 10_000
+
+const reportSchema = z.object({
+  kind: z.enum(['global-error', 'window-error', 'unhandled-rejection', 'chunk-load-error', 'request-error']),
+  message: z.string().trim().min(1).max(2000),
+  digest: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).optional(),
+  path: z.string().max(300).optional(),
+  stack: z.string().max(20_000).optional(),
+  timestamp: z.string().datetime().optional(),
+})
+
+type RateLimiter = { tryConsume: () => boolean }
+
+function createRateLimiter(now: () => number = () => Date.now()): RateLimiter {
+  let windowStart = now()
+  let count = 0
+  return {
+    tryConsume() {
+      const timestamp = now()
+      if (timestamp - windowStart >= RATE_LIMIT_WINDOW_MS) {
+        windowStart = timestamp
+        count = 0
+      }
+      if (count >= MAX_REPORTS_PER_WINDOW) return false
+      count += 1
+      return true
+    },
+  }
+}
+
+function jsonError(status: number, code: string, message: string): Response {
+  return Response.json({ error: { code, message } }, { status })
+}
+
+const NOT_FOUND = () => jsonError(404, 'not_found', 'Not found.')
+
+function isAuthorized(request: Request, config: DevRuntimeServerConfig): boolean {
+  return isMatchingDevRuntimeToken(config.token, request.headers.get(DEV_RUNTIME_TOKEN_HEADER))
+}
+
+// A browser sends `Origin` on cross-origin requests; anything that does not
+// match the request's own host is rejected outright. Non-browser callers that
+// omit `Origin` still have to present the token.
+function isAcceptableOrigin(request: Request): boolean {
+  const origin = request.headers.get('origin')
+  if (!origin) return true
+  try {
+    return new URL(origin).host === new URL(request.url).host
+  } catch {
+    return false
+  }
+}
+
+export type DevRuntimeRouteOptions = {
+  resolveConfig?: () => DevRuntimeServerConfig
+}
+
+/**
+ * Dev-only status bridge for the in-app banner. It exposes only the
+ * supervisor's local runtime state and returns 404 whenever diagnostics are off
+ * or the supervisor is not running.
+ */
+export function createDevRuntimeStatusRoute(options: DevRuntimeRouteOptions = {}) {
+  const resolveConfig = options.resolveConfig ?? (() => resolveDevRuntimeServerConfig())
+
+  return async function GET(request: Request): Promise<Response> {
+    const config = resolveConfig()
+    if (!config.enabled) return NOT_FOUND()
+    if (!isAcceptableOrigin(request)) return jsonError(403, 'forbidden', 'Origin is not allowed.')
+    if (!isAuthorized(request, config)) return jsonError(403, 'forbidden', 'Invalid dev runtime token.')
+
+    const status = readDevRuntimeStatus(config)
+    if (!status) return jsonError(404, 'not_found', 'Runtime status is not available.')
+
+    return Response.json(status, { headers: { 'cache-control': 'no-store' } })
+  }
+}
+
+export function createDevRuntimeDiagnosticsRoute(options: DevRuntimeRouteOptions = {}) {
+  const resolveConfig = options.resolveConfig ?? (() => resolveDevRuntimeServerConfig())
+  const limiter = createRateLimiter()
+
+  return async function POST(request: Request): Promise<Response> {
+    const config = resolveConfig()
+    if (!config.enabled) return NOT_FOUND()
+    if (!isAcceptableOrigin(request)) return jsonError(403, 'forbidden', 'Origin is not allowed.')
+    if (!isAuthorized(request, config)) return jsonError(403, 'forbidden', 'Invalid dev runtime token.')
+
+    const contentType = request.headers.get('content-type') ?? ''
+    if (!contentType.toLowerCase().includes('application/json')) {
+      return jsonError(400, 'invalid_report', 'Diagnostic report must be JSON.')
+    }
+
+    const body = await request.text()
+    if (Buffer.byteLength(body, 'utf8') > MAX_DEV_RUNTIME_REPORT_BYTES) {
+      return jsonError(400, 'report_too_large', 'Diagnostic report exceeds the size limit.')
+    }
+
+    let parsedBody: unknown
+    try {
+      parsedBody = JSON.parse(body)
+    } catch {
+      return jsonError(400, 'invalid_report', 'Diagnostic report is not valid JSON.')
+    }
+
+    const parsed = reportSchema.safeParse(parsedBody)
+    if (!parsed.success) {
+      return jsonError(400, 'invalid_report', 'Diagnostic report failed validation.')
+    }
+
+    if (!limiter.tryConsume()) {
+      return jsonError(429, 'rate_limited', 'Too many diagnostic reports.')
+    }
+
+    const message = redactDevRuntimeText(parsed.data.message, 500)
+    if (!message) return jsonError(400, 'invalid_report', 'Diagnostic report message is empty after redaction.')
+
+    const report: DevRuntimeReport = { kind: parsed.data.kind, message }
+    if (parsed.data.digest) report.digest = parsed.data.digest
+    const sanitizedPath = redactDevRuntimeText(parsed.data.path, 300)
+    if (sanitizedPath) report.path = sanitizedPath.startsWith('/') ? sanitizedPath : `/${sanitizedPath}`
+    const sanitizedStack = redactDevRuntimeText(parsed.data.stack, 2000)
+    if (sanitizedStack) report.stack = sanitizedStack
+    report.timestamp = parsed.data.timestamp ?? new Date().toISOString()
+
+    if (!appendDevRuntimeReport(config, report)) {
+      return jsonError(503, 'collector_unavailable', 'Diagnostic collector is unavailable.')
+    }
+
+    return Response.json({ accepted: true, issueId: `${report.kind}:${report.timestamp}` }, { status: 202 })
+  }
+}
+
+/**
+ * Dev-only recovery bridge for the in-app banner. The action is matched against
+ * the fixed allowlist and queued for the supervisor, which owns the actual
+ * lifecycle step — this route never spawns a process itself.
+ */
+export function createDevRuntimeActionsRoute(options: DevRuntimeRouteOptions = {}) {
+  const resolveConfig = options.resolveConfig ?? (() => resolveDevRuntimeServerConfig())
+
+  return async function POST(request: Request, context: { params: Promise<{ action: string }> }): Promise<Response> {
+    const config = resolveConfig()
+    if (!config.enabled) return NOT_FOUND()
+    if (!isAcceptableOrigin(request)) return jsonError(403, 'forbidden', 'Origin is not allowed.')
+    if (!isAuthorized(request, config)) return jsonError(403, 'forbidden', 'Invalid dev runtime token.')
+
+    const { action } = await context.params
+    if (!DEV_RUNTIME_RECOVERY_ACTIONS.includes(action as RuntimeRecoveryAction)) {
+      return jsonError(400, 'unknown_action', 'Unknown recovery action.')
+    }
+
+    const status = readDevRuntimeStatus(config)
+    if (!status) return jsonError(503, 'supervisor_unavailable', 'The supervisor is not available.')
+    // Serialization is enforced again by the runner; rejecting here just gives
+    // the banner an immediate, accurate answer instead of a silent queue.
+    if (status.recovery?.busy) {
+      return jsonError(409, 'action_busy', `The "${status.recovery.action}" action is still running.`)
+    }
+
+    const requestedAt = new Date().toISOString()
+    const queued = appendDevRuntimeActionRequest(config, {
+      action: action as RuntimeRecoveryAction,
+      generation: status.generation,
+      requestedAt,
+    })
+    if (!queued) return jsonError(503, 'supervisor_unavailable', 'The supervisor cannot accept recovery actions.')
+
+    return Response.json(
+      { accepted: true, actionId: `${status.generation}:${action}:${requestedAt}`, generation: status.generation },
+      { status: 202 },
+    )
+  }
+}
+
+/**
+ * Dev-only bounded log tail for the in-app logs view. Serving it from the app
+ * keeps the developer on the page they are debugging instead of bouncing them
+ * to the standalone splash on another port.
+ */
+export function createDevRuntimeLogsRoute(options: DevRuntimeRouteOptions = {}) {
+  const resolveConfig = options.resolveConfig ?? (() => resolveDevRuntimeServerConfig())
+
+  return async function GET(request: Request): Promise<Response> {
+    const config = resolveConfig()
+    if (!config.enabled) return NOT_FOUND()
+    if (!isAcceptableOrigin(request)) return jsonError(403, 'forbidden', 'Origin is not allowed.')
+    if (!isAuthorized(request, config)) return jsonError(403, 'forbidden', 'Invalid dev runtime token.')
+
+    // A malformed cursor restarts the snapshot rather than failing the view.
+    const raw = new URL(request.url).searchParams.get('cursor')
+    const parsed = Number.parseInt(raw ?? '', 10)
+    const snapshot = readDevRuntimeLogs(config, Number.isInteger(parsed) && parsed >= 0 ? parsed : 0)
+    if (!snapshot) return jsonError(404, 'not_found', 'Runtime logs are not available.')
+
+    return Response.json(snapshot, { headers: { 'cache-control': 'no-store' } })
+  }
+}

package/src/lib/dev-runtime/server.ts

@@ -0,0 +1,174 @@
+import { appendFileSync, readFileSync } from 'node:fs'
+import { timingSafeEqual } from 'node:crypto'
+
+import type {
+  DevRuntimeLogLine,
+  DevRuntimeLogSnapshot,
+  DevRuntimeReport,
+  DevRuntimeRecoveryAction,
+  RuntimeStatus,
+} from './types'
+
+export type DevRuntimeServerConfig = {
+  enabled: boolean
+  bannerEnabled: boolean
+  token: string | null
+  statusFilePath: string | null
+  diagnosticsFilePath: string | null
+  actionsFilePath: string | null
+  logsFilePath: string | null
+}
+
+const DISABLED_CONFIG: DevRuntimeServerConfig = {
+  enabled: false,
+  bannerEnabled: false,
+  token: null,
+  statusFilePath: null,
+  diagnosticsFilePath: null,
+  actionsFilePath: null,
+  logsFilePath: null,
+}
+
+function readFlag(value: string | undefined, fallback: boolean): boolean {
+  if (typeof value !== 'string' || value.trim() === '') return fallback
+  const normalized = value.trim().toLowerCase()
+  if (['1', 'true', 'on', 'yes', 'enabled'].includes(normalized)) return true
+  if (['0', 'false', 'off', 'no', 'disabled'].includes(normalized)) return false
+  return fallback
+}
+
+function readNonEmpty(value: string | undefined): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+/**
+ * Dev diagnostics exist only while a local `yarn dev` supervisor is managing
+ * this process.
+ *
+ * NODE_ENV is deliberately NOT the guard: `mercato dev` spawns the Next.js dev
+ * server through `buildServerProcessEnvironment`, which forces
+ * `NODE_ENV=production` (the same helper already forces the logging facade to
+ * re-apply its dev defaults by hand). Keying off it would disable diagnostics
+ * in exactly the environment they exist for.
+ *
+ * The real discriminator is the supervisor handshake: the per-run token and the
+ * two state-file paths are injected by `createDevRuntimeSupervisor().childEnv()`
+ * and exist nowhere else. A deployed `mercato server` has no supervisor, so it
+ * has none of them and every route stays closed — even if someone sets
+ * `OM_DEV_RUNTIME_DIAGNOSTICS` by hand.
+ */
+export function resolveDevRuntimeServerConfig(env: NodeJS.ProcessEnv = process.env): DevRuntimeServerConfig {
+  if (!readFlag(env.OM_DEV_RUNTIME_DIAGNOSTICS, false)) return DISABLED_CONFIG
+
+  const token = readNonEmpty(env.OM_DEV_RUNTIME_TOKEN)
+  const statusFilePath = readNonEmpty(env.OM_DEV_RUNTIME_STATUS_FILE)
+  const diagnosticsFilePath = readNonEmpty(env.OM_DEV_RUNTIME_DIAGNOSTICS_FILE)
+  if (!token || !statusFilePath || !diagnosticsFilePath) return DISABLED_CONFIG
+
+  return {
+    enabled: true,
+    bannerEnabled: readFlag(env.OM_DEV_RUNTIME_BANNER, true),
+    token,
+    statusFilePath,
+    diagnosticsFilePath,
+    // Absent when the supervisor predates the action channel; the actions route
+    // then reports itself unavailable rather than silently dropping requests.
+    actionsFilePath: readNonEmpty(env.OM_DEV_RUNTIME_ACTIONS_FILE),
+    logsFilePath: readNonEmpty(env.OM_DEV_RUNTIME_LOGS_FILE),
+  }
+}
+
+export function isMatchingDevRuntimeToken(expected: string | null, provided: string | null): boolean {
+  if (!expected || !provided) return false
+  const expectedBuffer = Buffer.from(expected)
+  const providedBuffer = Buffer.from(provided)
+  if (expectedBuffer.length !== providedBuffer.length) return false
+  return timingSafeEqual(expectedBuffer, providedBuffer)
+}
+
+type SupervisorStatusFile = {
+  token?: unknown
+  pid?: unknown
+  status?: unknown
+}
+
+function isRuntimeStatus(value: unknown): value is RuntimeStatus {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<RuntimeStatus>
+  return typeof candidate.health === 'string'
+    && typeof candidate.generation === 'number'
+    && Array.isArray(candidate.incidents)
+}
+
+/**
+ * Reads the supervisor-owned status file. The route never derives status from
+ * application state, so it cannot leak module, tenant, or organization data.
+ */
+export function readDevRuntimeStatus(config: DevRuntimeServerConfig): RuntimeStatus | null {
+  if (!config.enabled || !config.statusFilePath) return null
+  let parsed: SupervisorStatusFile
+  try {
+    parsed = JSON.parse(readFileSync(config.statusFilePath, 'utf8')) as SupervisorStatusFile
+  } catch {
+    return null
+  }
+  // A status file written by a different run must not be served: its token is
+  // stale and its generation would confuse the banner.
+  if (typeof parsed.token !== 'string' || !isMatchingDevRuntimeToken(config.token, parsed.token)) return null
+  return isRuntimeStatus(parsed.status) ? parsed.status : null
+}
+
+export function appendDevRuntimeReport(config: DevRuntimeServerConfig, report: DevRuntimeReport): boolean {
+  if (!config.enabled || !config.diagnosticsFilePath) return false
+  try {
+    appendFileSync(config.diagnosticsFilePath, `${JSON.stringify(report)}\n`, 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function appendDevRuntimeActionRequest(
+  config: DevRuntimeServerConfig,
+  request: { action: DevRuntimeRecoveryAction; generation?: number; requestedAt: string },
+): boolean {
+  if (!config.enabled || !config.actionsFilePath) return false
+  try {
+    appendFileSync(config.actionsFilePath, `${JSON.stringify(request)}\n`, 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Reads the supervisor-published log tail. Lines are already bounded and
+ * redacted by the collector; this only filters by cursor so the logs view can
+ * poll incrementally.
+ */
+export function readDevRuntimeLogs(
+  config: DevRuntimeServerConfig,
+  cursor = 0,
+): DevRuntimeLogSnapshot | null {
+  if (!config.enabled || !config.logsFilePath) return null
+  let parsed: { token?: unknown; generation?: unknown; lines?: unknown }
+  try {
+    parsed = JSON.parse(readFileSync(config.logsFilePath, 'utf8'))
+  } catch {
+    return null
+  }
+  if (typeof parsed.token !== 'string' || !isMatchingDevRuntimeToken(config.token, parsed.token)) return null
+  if (!Array.isArray(parsed.lines)) return null
+
+  const from = Number.isInteger(cursor) && cursor >= 0 ? cursor : 0
+  const lines = (parsed.lines as DevRuntimeLogLine[]).filter((line) => (
+    line && typeof line === 'object' && typeof line.text === 'string' && Number(line.seq) > from
+  ))
+  return {
+    generation: typeof parsed.generation === 'number' ? parsed.generation : 0,
+    lines,
+    nextCursor: lines.length > 0 ? Number(lines[lines.length - 1].seq) : from,
+  }
+}

package/src/lib/dev-runtime/types.ts

@@ -0,0 +1,101 @@
+export const RUNTIME_STATUS_SCHEMA_VERSION = 1 as const
+
+export type RuntimeHealth =
+  | 'starting'
+  | 'ready'
+  | 'degraded'
+  | 'recovering'
+  | 'unavailable'
+
+export type RuntimeIssueSource = 'process' | 'log' | 'warmup' | 'probe' | 'browser'
+export type RuntimeIssueSeverity = 'warning' | 'error'
+export type RuntimeRecoveryAction = 'generate' | 'migrate' | 'restart'
+export type DevRuntimeRecoveryAction = RuntimeRecoveryAction
+export const DEV_RUNTIME_RECOVERY_ACTIONS: RuntimeRecoveryAction[] = ['generate', 'migrate', 'restart']
+
+export type RuntimeIssue = {
+  id: string
+  fingerprint: string
+  code: string
+  source: RuntimeIssueSource
+  severity: RuntimeIssueSeverity
+  title: string
+  detail?: string
+  firstSeenAt: string
+  lastSeenAt: string
+  occurrences: number
+  generation: number
+  path?: string
+  digest?: string
+  recovery?: RuntimeRecoveryAction
+}
+
+export type RuntimeStatus = {
+  schemaVersion: typeof RUNTIME_STATUS_SCHEMA_VERSION
+  generation: number
+  health: RuntimeHealth
+  ready: boolean
+  failed: boolean
+  updatedAt: string
+  upstream: {
+    configuredPort: number
+    actualPort?: number
+    publicUrl: string
+  }
+  issueSummary?: RuntimeIssue
+  incidents: RuntimeIssue[]
+  recovery?: {
+    action: RuntimeRecoveryAction
+    startedAt: string
+    busy: boolean
+    lastExitCode?: number
+  }
+  legacy: {
+    failureLines: string[]
+    failureCommand?: string
+    failureStage?: string
+  }
+}
+
+export type DevRuntimeReportKind =
+  | 'global-error'
+  | 'window-error'
+  | 'unhandled-rejection'
+  | 'chunk-load-error'
+  | 'request-error'
+
+export type DevRuntimeReport = {
+  kind: DevRuntimeReportKind
+  message: string
+  digest?: string
+  path?: string
+  stack?: string
+  timestamp?: string
+}
+
+export const DEV_RUNTIME_TOKEN_HEADER = 'x-om-dev-runtime-token'
+export const DEV_RUNTIME_TOKEN_META_NAME = 'om-dev-runtime-token'
+export const DEV_RUNTIME_BANNER_META_NAME = 'om-dev-runtime-banner'
+export const DEV_RUNTIME_LOGS_URL_META_NAME = 'om-dev-runtime-logs-url'
+// Kebab-case on purpose: module ids are snake_case, so this segment can never
+// collide with a module's `/api/<module_id>/...` routes. A leading-underscore
+// path is not an option — Next.js treats `_folder` as a private folder and drops
+// it from the route tree entirely.
+export const DEV_RUNTIME_STATUS_PATH = '/api/dev-runtime/status'
+export const DEV_RUNTIME_DIAGNOSTICS_PATH = '/api/dev-runtime/diagnostics'
+export const DEV_RUNTIME_ACTIONS_PATH = '/api/dev-runtime/actions'
+export const DEV_RUNTIME_LOGS_PATH = '/api/dev-runtime/logs'
+
+export type DevRuntimeLogLine = {
+  seq: number
+  at: string
+  generation: number
+  source: string
+  text: string
+}
+
+export type DevRuntimeLogSnapshot = {
+  generation: number
+  lines: DevRuntimeLogLine[]
+  nextCursor: number
+}