@open-mercato/shared 0.7.1-develop.7151.1.00d0391847 → 0.7.1-develop.7152.1.a69e92f9c9

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

@@ -0,0 +1,473 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import {
+  createDevRuntimeActionsRoute,
+  createDevRuntimeLogsRoute,
+  createDevRuntimeDiagnosticsRoute,
+  createDevRuntimeStatusRoute,
+} from '../routes'
+import { readDevRuntimeStatus, resolveDevRuntimeServerConfig, type DevRuntimeServerConfig } from '../server'
+import { DEV_RUNTIME_TOKEN_HEADER, type RuntimeStatus } from '../types'
+
+const TOKEN = 'dev-runtime-token-fixture'
+
+function createStatus(overrides: Partial<RuntimeStatus> = {}): RuntimeStatus {
+  return {
+    schemaVersion: 1,
+    generation: 1,
+    health: 'degraded',
+    ready: true,
+    failed: false,
+    updatedAt: '2026-08-18T10:00:00.000Z',
+    upstream: { configuredPort: 3000, publicUrl: 'http://localhost:3000' },
+    incidents: [],
+    legacy: { failureLines: [] },
+    ...overrides,
+  }
+}
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'om-dev-runtime-routes-'))
+}
+
+function createConfig(directory: string, overrides: Partial<DevRuntimeServerConfig> = {}): DevRuntimeServerConfig {
+  return {
+    enabled: true,
+    bannerEnabled: true,
+    token: TOKEN,
+    statusFilePath: path.join(directory, 'status.json'),
+    diagnosticsFilePath: path.join(directory, 'diagnostics.ndjson'),
+    actionsFilePath: path.join(directory, 'actions.ndjson'),
+    logsFilePath: path.join(directory, 'logs.json'),
+    ...overrides,
+  }
+}
+
+function writeStatusFile(config: DevRuntimeServerConfig, status: RuntimeStatus, token = TOKEN): void {
+  fs.writeFileSync(config.statusFilePath!, JSON.stringify({ token, pid: process.pid, status }), 'utf8')
+}
+
+function statusRequest(headers: Record<string, string> = { [DEV_RUNTIME_TOKEN_HEADER]: TOKEN }): Request {
+  return new Request('http://localhost:3000/api/dev-runtime/status', { headers })
+}
+
+function diagnosticsRequest(body: unknown, headers: Record<string, string> = {}): Request {
+  return new Request('http://localhost:3000/api/dev-runtime/diagnostics', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      [DEV_RUNTIME_TOKEN_HEADER]: TOKEN,
+      ...headers,
+    },
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+  })
+}
+
+describe('resolveDevRuntimeServerConfig', () => {
+  const baseEnv = {
+    NODE_ENV: 'development',
+    OM_DEV_RUNTIME_DIAGNOSTICS: '1',
+    OM_DEV_RUNTIME_TOKEN: TOKEN,
+    OM_DEV_RUNTIME_STATUS_FILE: '/tmp/status.json',
+    OM_DEV_RUNTIME_DIAGNOSTICS_FILE: '/tmp/diagnostics.ndjson',
+  } as NodeJS.ProcessEnv
+
+  it('enables diagnostics only for a supervised development process', () => {
+    expect(resolveDevRuntimeServerConfig(baseEnv).enabled).toBe(true)
+  })
+
+  // `mercato dev` runs the Next.js dev server with NODE_ENV=production
+  // (buildServerProcessEnvironment), so NODE_ENV cannot be the production guard
+  // — the supervisor handshake is.
+  it('stays enabled under NODE_ENV=production while the supervisor handshake is present', () => {
+    expect(resolveDevRuntimeServerConfig({ ...baseEnv, NODE_ENV: 'production' }).enabled).toBe(true)
+  })
+
+  it('stays disabled for a deployed server that has no supervisor handshake', () => {
+    // What a real `mercato server` process looks like: no token, no state files.
+    expect(resolveDevRuntimeServerConfig({
+      NODE_ENV: 'production',
+      OM_DEV_RUNTIME_DIAGNOSTICS: '1',
+    } as NodeJS.ProcessEnv).enabled).toBe(false)
+  })
+
+  it('stays disabled without an explicit flag', () => {
+    const { OM_DEV_RUNTIME_DIAGNOSTICS: _flag, ...withoutFlag } = baseEnv
+    expect(resolveDevRuntimeServerConfig(withoutFlag).enabled).toBe(false)
+  })
+
+  it('stays disabled when the supervisor did not supply a token or paths', () => {
+    expect(resolveDevRuntimeServerConfig({ ...baseEnv, OM_DEV_RUNTIME_TOKEN: '' }).enabled).toBe(false)
+    expect(resolveDevRuntimeServerConfig({ ...baseEnv, OM_DEV_RUNTIME_STATUS_FILE: '' }).enabled).toBe(false)
+    expect(resolveDevRuntimeServerConfig({ ...baseEnv, OM_DEV_RUNTIME_DIAGNOSTICS_FILE: '' }).enabled).toBe(false)
+  })
+
+  it('honours the banner opt-out independently', () => {
+    expect(resolveDevRuntimeServerConfig({ ...baseEnv, OM_DEV_RUNTIME_BANNER: '0' })).toMatchObject({
+      enabled: true,
+      bannerEnabled: false,
+    })
+  })
+})
+
+describe('readDevRuntimeStatus', () => {
+  let directory: string
+
+  beforeEach(() => { directory = createTempDir() })
+  afterEach(() => { fs.rmSync(directory, { recursive: true, force: true }) })
+
+  it('returns the supervisor status', () => {
+    const config = createConfig(directory)
+    writeStatusFile(config, createStatus())
+    expect(readDevRuntimeStatus(config)?.health).toBe('degraded')
+  })
+
+  it('rejects a status file written by a different run', () => {
+    const config = createConfig(directory)
+    writeStatusFile(config, createStatus(), 'a-stale-token-of-len')
+    expect(readDevRuntimeStatus(config)).toBeNull()
+  })
+
+  it('returns null for a missing or malformed file', () => {
+    const config = createConfig(directory)
+    expect(readDevRuntimeStatus(config)).toBeNull()
+    fs.writeFileSync(config.statusFilePath!, 'not json', 'utf8')
+    expect(readDevRuntimeStatus(config)).toBeNull()
+    fs.writeFileSync(config.statusFilePath!, JSON.stringify({ token: TOKEN, status: { nope: true } }), 'utf8')
+    expect(readDevRuntimeStatus(config)).toBeNull()
+  })
+})
+
+describe('createDevRuntimeStatusRoute', () => {
+  let directory: string
+
+  beforeEach(() => { directory = createTempDir() })
+  afterEach(() => { fs.rmSync(directory, { recursive: true, force: true }) })
+
+  it('serves the supervisor status for a valid token', async () => {
+    const config = createConfig(directory)
+    writeStatusFile(config, createStatus())
+    const GET = createDevRuntimeStatusRoute({ resolveConfig: () => config })
+
+    const response = await GET(statusRequest())
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    await expect(response.json()).resolves.toMatchObject({ health: 'degraded', generation: 1 })
+  })
+
+  it('returns 404 when diagnostics are disabled', async () => {
+    const GET = createDevRuntimeStatusRoute({ resolveConfig: () => createConfig(directory, { enabled: false }) })
+    const response = await GET(statusRequest())
+    expect(response.status).toBe(404)
+  })
+
+  it('returns 403 for a missing or wrong token', async () => {
+    const config = createConfig(directory)
+    writeStatusFile(config, createStatus())
+    const GET = createDevRuntimeStatusRoute({ resolveConfig: () => config })
+
+    await expect(GET(statusRequest({})).then((r) => r.status)).resolves.toBe(403)
+    await expect(
+      GET(statusRequest({ [DEV_RUNTIME_TOKEN_HEADER]: 'wrong-token-value-xx' })).then((r) => r.status),
+    ).resolves.toBe(403)
+  })
+
+  it('rejects a cross-origin request', async () => {
+    const config = createConfig(directory)
+    writeStatusFile(config, createStatus())
+    const GET = createDevRuntimeStatusRoute({ resolveConfig: () => config })
+
+    const response = await GET(statusRequest({
+      [DEV_RUNTIME_TOKEN_HEADER]: TOKEN,
+      origin: 'http://evil.example',
+    }))
+    expect(response.status).toBe(403)
+  })
+
+  it('returns 404 while the supervisor state is unavailable', async () => {
+    const GET = createDevRuntimeStatusRoute({ resolveConfig: () => createConfig(directory) })
+    const response = await GET(statusRequest())
+    expect(response.status).toBe(404)
+  })
+})
+
+describe('createDevRuntimeDiagnosticsRoute', () => {
+  let directory: string
+  let config: DevRuntimeServerConfig
+
+  beforeEach(() => {
+    directory = createTempDir()
+    config = createConfig(directory)
+  })
+  afterEach(() => { fs.rmSync(directory, { recursive: true, force: true }) })
+
+  function readSink(): Array<Record<string, unknown>> {
+    if (!fs.existsSync(config.diagnosticsFilePath!)) return []
+    return fs.readFileSync(config.diagnosticsFilePath!, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as Record<string, unknown>)
+  }
+
+  it('accepts a valid report and appends it to the local sink', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    const response = await POST(diagnosticsRequest({
+      kind: 'global-error',
+      message: 'TypeError: x is not a function',
+      digest: 'abc123',
+      path: '/backend/example',
+    }))
+
+    expect(response.status).toBe(202)
+    await expect(response.json()).resolves.toMatchObject({ accepted: true })
+    expect(readSink()).toEqual([expect.objectContaining({
+      kind: 'global-error',
+      message: 'TypeError: x is not a function',
+      path: '/backend/example',
+    })])
+  })
+
+  it('returns 404 when diagnostics are disabled', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => createConfig(directory, { enabled: false }) })
+    const response = await POST(diagnosticsRequest({ kind: 'global-error', message: 'boom' }))
+    expect(response.status).toBe(404)
+    expect(readSink()).toEqual([])
+  })
+
+  it('returns 403 for a missing token', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    const request = new Request('http://localhost:3000/api/dev-runtime/diagnostics', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ kind: 'global-error', message: 'boom' }),
+    })
+    expect((await POST(request)).status).toBe(403)
+    expect(readSink()).toEqual([])
+  })
+
+  it('rejects a non-JSON content type', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    const request = new Request('http://localhost:3000/api/dev-runtime/diagnostics', {
+      method: 'POST',
+      headers: { 'content-type': 'text/plain', [DEV_RUNTIME_TOKEN_HEADER]: TOKEN },
+      body: 'boom',
+    })
+    expect((await POST(request)).status).toBe(400)
+  })
+
+  it('rejects an invalid schema', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    expect((await POST(diagnosticsRequest({ kind: 'shell-exec', message: 'boom' }))).status).toBe(400)
+    expect((await POST(diagnosticsRequest({ kind: 'global-error' }))).status).toBe(400)
+    expect((await POST(diagnosticsRequest({ kind: 'global-error', message: 'x', digest: 'a b' }))).status).toBe(400)
+    expect((await POST(diagnosticsRequest('{not json'))).status).toBe(400)
+    expect(readSink()).toEqual([])
+  })
+
+  it('rejects an oversized body before parsing it', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    const response = await POST(diagnosticsRequest({ kind: 'global-error', message: 'x'.repeat(20_000) }))
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toMatchObject({ error: { code: 'report_too_large' } })
+  })
+
+  it('redacts secrets before writing to the sink', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    await POST(diagnosticsRequest({
+      kind: 'window-error',
+      message: 'failed for postgres://admin:hunter2@localhost:5432/app',
+      stack: 'cookie: om_session=super-secret',
+    }))
+
+    const written = JSON.stringify(readSink())
+    expect(written).not.toContain('hunter2')
+    expect(written).not.toContain('super-secret')
+    expect(written).toContain('postgres://***')
+  })
+
+  it('rate limits a looping reporter', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({ resolveConfig: () => config })
+    const statuses: number[] = []
+    for (let index = 0; index < 35; index += 1) {
+      statuses.push((await POST(diagnosticsRequest({ kind: 'global-error', message: `boom ${index}` }))).status)
+    }
+    expect(statuses.filter((status) => status === 202)).toHaveLength(30)
+    expect(statuses.filter((status) => status === 429)).toHaveLength(5)
+  })
+
+  it('reports a collector failure instead of throwing', async () => {
+    const POST = createDevRuntimeDiagnosticsRoute({
+      resolveConfig: () => createConfig(directory, {
+        diagnosticsFilePath: path.join(directory, 'missing-directory', 'diagnostics.ndjson'),
+      }),
+    })
+    const response = await POST(diagnosticsRequest({ kind: 'global-error', message: 'boom' }))
+    expect(response.status).toBe(503)
+  })
+})
+
+describe('createDevRuntimeActionsRoute', () => {
+  let directory: string
+  let config: DevRuntimeServerConfig
+
+  beforeEach(() => {
+    directory = createTempDir()
+    config = createConfig(directory)
+  })
+  afterEach(() => { fs.rmSync(directory, { recursive: true, force: true }) })
+
+  function actionRequest(action: string, headers: Record<string, string> = { [DEV_RUNTIME_TOKEN_HEADER]: TOKEN }): [Request, { params: Promise<{ action: string }> }] {
+    return [
+      new Request(`http://localhost:3000/api/dev-runtime/actions/${action}`, { method: 'POST', headers }),
+      { params: Promise.resolve({ action }) },
+    ]
+  }
+
+  function readQueue(): Array<Record<string, unknown>> {
+    if (!fs.existsSync(config.actionsFilePath!)) return []
+    return fs.readFileSync(config.actionsFilePath!, 'utf8')
+      .split('\n').filter(Boolean)
+      .map((line) => JSON.parse(line) as Record<string, unknown>)
+  }
+
+  it('queues an allowlisted action with the current generation', async () => {
+    writeStatusFile(config, createStatus({ generation: 7 }))
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => config })
+
+    const response = await POST(...actionRequest('migrate'))
+    expect(response.status).toBe(202)
+    await expect(response.json()).resolves.toMatchObject({ accepted: true, generation: 7 })
+    expect(readQueue()).toEqual([expect.objectContaining({ action: 'migrate', generation: 7 })])
+  })
+
+  it('rejects an action outside the allowlist without queueing anything', async () => {
+    writeStatusFile(config, createStatus())
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => config })
+
+    const response = await POST(...actionRequest('rm-rf'))
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toMatchObject({ error: { code: 'unknown_action' } })
+    expect(readQueue()).toEqual([])
+  })
+
+  it('returns 403 for a missing or wrong token', async () => {
+    writeStatusFile(config, createStatus())
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => config })
+
+    expect((await POST(...actionRequest('restart', {}))).status).toBe(403)
+    expect((await POST(...actionRequest('restart', { [DEV_RUNTIME_TOKEN_HEADER]: 'wrong-token-value-xx' }))).status).toBe(403)
+    expect(readQueue()).toEqual([])
+  })
+
+  it('rejects a cross-origin request', async () => {
+    writeStatusFile(config, createStatus())
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => config })
+    const response = await POST(...actionRequest('restart', {
+      [DEV_RUNTIME_TOKEN_HEADER]: TOKEN,
+      origin: 'http://evil.example',
+    }))
+    expect(response.status).toBe(403)
+  })
+
+  it('returns 404 when diagnostics are disabled', async () => {
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => createConfig(directory, { enabled: false }) })
+    expect((await POST(...actionRequest('restart'))).status).toBe(404)
+  })
+
+  it('reports a conflict while another action is running', async () => {
+    writeStatusFile(config, createStatus({
+      recovery: { action: 'generate', startedAt: '2026-08-18T10:00:00.000Z', busy: true },
+    }))
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => config })
+
+    const response = await POST(...actionRequest('migrate'))
+    expect(response.status).toBe(409)
+    await expect(response.json()).resolves.toMatchObject({ error: { code: 'action_busy' } })
+    expect(readQueue()).toEqual([])
+  })
+
+  it('reports 503 when the supervisor state is unavailable', async () => {
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => config })
+    expect((await POST(...actionRequest('restart'))).status).toBe(503)
+  })
+
+  it('reports 503 when the supervisor exposed no action channel', async () => {
+    const withoutChannel = createConfig(directory, { actionsFilePath: null })
+    writeStatusFile(withoutChannel, createStatus())
+    const POST = createDevRuntimeActionsRoute({ resolveConfig: () => withoutChannel })
+    expect((await POST(...actionRequest('restart'))).status).toBe(503)
+  })
+})
+
+describe('createDevRuntimeLogsRoute', () => {
+  let directory: string
+  let config: DevRuntimeServerConfig
+
+  beforeEach(() => {
+    directory = createTempDir()
+    config = createConfig(directory)
+  })
+  afterEach(() => { fs.rmSync(directory, { recursive: true, force: true }) })
+
+  function writeLogs(lines: Array<Record<string, unknown>>, token = TOKEN): void {
+    fs.writeFileSync(config.logsFilePath!, JSON.stringify({ token, generation: 1, lines }), 'utf8')
+  }
+
+  function logsRequest(cursor?: number, headers: Record<string, string> = { [DEV_RUNTIME_TOKEN_HEADER]: TOKEN }): Request {
+    const suffix = cursor === undefined ? '' : `?cursor=${cursor}`
+    return new Request(`http://localhost:3000/api/dev-runtime/logs${suffix}`, { headers })
+  }
+
+  const LINES = [
+    { seq: 1, at: '2026-08-18T10:00:01.000Z', generation: 1, source: 'log', text: 'first' },
+    { seq: 2, at: '2026-08-18T10:00:02.000Z', generation: 1, source: 'log', text: 'second' },
+  ]
+
+  it('serves the bounded log tail', async () => {
+    writeLogs(LINES)
+    const GET = createDevRuntimeLogsRoute({ resolveConfig: () => config })
+    const response = await GET(logsRequest())
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({ generation: 1, nextCursor: 2 })
+  })
+
+  it('honours the cursor so the view can poll incrementally', async () => {
+    writeLogs(LINES)
+    const GET = createDevRuntimeLogsRoute({ resolveConfig: () => config })
+    const body = await (await GET(logsRequest(1))).json()
+    expect(body.lines).toEqual([expect.objectContaining({ seq: 2, text: 'second' })])
+  })
+
+  it('restarts the snapshot on a malformed cursor instead of failing', async () => {
+    writeLogs(LINES)
+    const GET = createDevRuntimeLogsRoute({ resolveConfig: () => config })
+    const response = await GET(new Request('http://localhost:3000/api/dev-runtime/logs?cursor=nope', {
+      headers: { [DEV_RUNTIME_TOKEN_HEADER]: TOKEN },
+    }))
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({ nextCursor: 2 })
+  })
+
+  it('rejects a missing token, a wrong origin and a disabled runtime', async () => {
+    writeLogs(LINES)
+    const GET = createDevRuntimeLogsRoute({ resolveConfig: () => config })
+    expect((await GET(logsRequest(0, {}))).status).toBe(403)
+    expect((await GET(logsRequest(0, { [DEV_RUNTIME_TOKEN_HEADER]: TOKEN, origin: 'http://evil.example' }))).status).toBe(403)
+
+    const disabled = createDevRuntimeLogsRoute({ resolveConfig: () => createConfig(directory, { enabled: false }) })
+    expect((await disabled(logsRequest())).status).toBe(404)
+  })
+
+  it('rejects a log file written by a different run', async () => {
+    writeLogs(LINES, 'a-stale-token-of-len')
+    const GET = createDevRuntimeLogsRoute({ resolveConfig: () => config })
+    expect((await GET(logsRequest())).status).toBe(404)
+  })
+
+  it('returns 404 when the supervisor published no logs', async () => {
+    const GET = createDevRuntimeLogsRoute({ resolveConfig: () => config })
+    expect((await GET(logsRequest())).status).toBe(404)
+  })
+})

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()
+}