@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.51

package/server-managed/bundle-commits.ts

@@ -0,0 +1,140 @@
+import { setImmediate } from 'node:timers/promises'
+import { bundleCommitHash } from '../common/bundle-commit.js'
+import type { BundleSummary } from './bundle-cache.ts'
+import type { ManagedDb } from './db.ts'
+import { type GithubCommit, githubCommitKey } from './github-metadata.ts'
+
+const MAX_MESSAGE_LENGTH = 65_536
+const MAX_NAME_LENGTH = 256
+// GitHub logins, and the `[bot]` accounts apps commit as.
+const GITHUB_LOGIN = /^[A-Za-z\d][A-Za-z\d-]{0,38}(?:\[bot\])?$/u
+const BACKFILL_LIMIT = 4
+const RETRY_MS = 5 * 60_000
+
+export type CommitDetails = Omit<GithubCommit, 'key' | 'fetchedAt'>
+// What viewers see of a cached commit: its subject in place of the message.
+export type CatalogCommitDetails = Omit<CommitDetails, 'message'> & { subject: string }
+// What a catalog sends with a bundle whose summary records a commit, when
+// the cache holds its details, tags pointing to it, or both. `github` is the
+// repository they were cached for: the one the bundle is stored at.
+export interface BundleCommitInfo { sha: string; github: string; tags: string[]; details: CatalogCommitDetails | null }
+interface CatalogBundle { integrity: string; repoId: number | null; repoFullName: string | null }
+type Summaries = ReadonlyMap<string, { summary: BundleSummary | null }>
+export interface CatalogCommit { repoId: number; sha: string; key: string }
+export interface CommitReader { commitDetails(sha: string): Promise<CommitDetails | null> }
+
+function truncate(value: string, max: number): string {
+  if (value.length <= max) return value
+  // Never leave half of a surrogate pair at the end.
+  return value.slice(0, /[\uD800-\uDBFF]/u.test(value[max - 1]!) ? max - 1 : max)
+}
+
+function name(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? truncate(value.trim(), MAX_NAME_LENGTH) : null
+}
+
+function date(value: unknown): number | null {
+  const time = typeof value === 'string' ? Date.parse(value) : NaN
+  return Number.isSafeInteger(time) ? time : null
+}
+
+// `body` is a GitHub list-commits page that starts at `sha`, so its first
+// commit is that one, without the files GET /commits/:sha would add.
+export function parseGithubCommit(sha: string, body: unknown): CommitDetails | null {
+  const item = Array.isArray(body) ? body[0] as {
+    sha?: unknown; author?: { login?: unknown } | null
+    commit?: { message?: unknown; author?: { name?: unknown; date?: unknown } | null; committer?: { date?: unknown } | null }
+  } | null : null
+  if (item?.sha !== sha || typeof item.commit?.message !== 'string') return null
+  const login = item.author?.login
+  return {
+    message: truncate(item.commit.message, MAX_MESSAGE_LENGTH),
+    authorName: name(item.commit.author?.name),
+    authorLogin: typeof login === 'string' && GITHUB_LOGIN.test(login) ? login : null,
+    authoredAt: date(item.commit.author?.date),
+    committedAt: date(item.commit.committer?.date),
+  }
+}
+
+// A commit's subject, as `git log --format=%s` gives it: the message's first
+// paragraph on one line, here without the Claude-Session lines Claude Code
+// adds. Viewers see no more of the message, so catalogs send no more.
+export function commitSubject(message: string): string {
+  const paragraph = message.replaceAll('\r\n', '\n').trim().split(/\n[ \t]*\n/u, 1)[0] ?? ''
+  return paragraph.split('\n').map(line => line.trim()).filter(line => line && !/^Claude-Session:/iu.test(line)).join(' ')
+}
+
+// The commit a bundle's own summary records, in the repository it is stored at.
+function catalogCommit(bundle: CatalogBundle, summaries: Summaries): CatalogCommit | null {
+  const sha = bundleCommitHash(summaries.get(bundle.integrity)?.summary?.commit)
+  return sha && bundle.repoId != null ? { repoId: bundle.repoId, sha, key: githubCommitKey(bundle.repoId, sha) } : null
+}
+
+// Reads only the cache: viewing a bundle never requests its commit's tags,
+// and a commit missing from the cache is left for backfillBundleCommits.
+// Call it before the catalog's final access check: `commitInfo` answers for
+// the bundles of that last snapshot without another await, and has nothing
+// for a commit or repository this read did not cover.
+export async function bundleCommits(db: ManagedDb, bundles: readonly CatalogBundle[], summaries: Summaries) {
+  const wanted = new Map<string, CatalogCommit>()
+  for (const bundle of bundles) {
+    const commit = catalogCommit(bundle, summaries)
+    if (commit) wanted.set(commit.key, commit)
+  }
+  const keys = [...wanted.keys()]
+  const details = new Map<string, CatalogCommitDetails>()
+  const tags = new Map<string, string[]>()
+  if (keys.length > 0) {
+    for (const { key, fetchedAt: _fetchedAt, message, ...commit } of await db.listGithubCommits(keys)) {
+      details.set(key, { subject: commitSubject(message), ...commit })
+    }
+    for (const tag of await db.listGithubCommitTags(keys)) tags.set(tag.key, [...tags.get(tag.key) ?? [], tag.name])
+  }
+  return {
+    commitInfo(bundle: CatalogBundle): BundleCommitInfo | null {
+      const commit = catalogCommit(bundle, summaries)
+      if (!commit || !bundle.repoFullName || (!details.has(commit.key) && !tags.has(commit.key))) return null
+      return { sha: commit.sha, github: bundle.repoFullName, tags: tags.get(commit.key) ?? [], details: details.get(commit.key) ?? null }
+    },
+    missing: [...wanted.values()].filter(commit => !details.has(commit.key)),
+  }
+}
+
+// Store the details of a commit, read with the reader's verified repository
+// access, unless the cache already has them. Best effort: true once cached.
+export async function cacheCommitDetails(db: ManagedDb, reader: CommitReader, repoId: number, sha: string): Promise<boolean> {
+  const key = githubCommitKey(repoId, sha)
+  try {
+    if ((await db.listGithubCommits([key])).length > 0) return true
+    const details = await reader.commitDetails(sha)
+    if (details) await db.setGithubCommits([{ key, ...details, fetchedAt: Date.now() }])
+    return details !== null
+  } catch { return false }
+}
+
+const active = new Set<string>()
+const retries = new Map<string, number>()
+
+// Called after the catalog response is sent: the next one has the details.
+// Reads each commit with the viewer's own repository access, so a viewer who
+// cannot read it on GitHub leaves it for another (retried after a delay for
+// them). Commits never change, so each is stored once and kept.
+export async function backfillBundleCommits(db: ManagedDb, userId: string, missing: readonly CatalogCommit[],
+  readerFor: (repoId: number) => Promise<CommitReader | null>): Promise<void> {
+  if (missing.length === 0) return
+  await setImmediate()
+  const now = Date.now()
+  for (const [key, retryAt] of retries) if (retryAt <= now) retries.delete(key)
+  const batch = missing.filter(commit => !active.has(commit.key) && !retries.has(`${userId}\n${commit.key}`)).slice(0, BACKFILL_LIMIT)
+  for (const commit of batch) active.add(commit.key)
+  try {
+    for (const repoId of new Set(batch.map(commit => commit.repoId))) {
+      const reader = await readerFor(repoId).catch(() => null)
+      for (const commit of batch.filter(entry => entry.repoId === repoId)) {
+        if (!reader || !await cacheCommitDetails(db, reader, repoId, commit.sha)) retries.set(`${userId}\n${commit.key}`, Date.now() + RETRY_MS)
+      }
+    }
+  } finally {
+    for (const commit of batch) active.delete(commit.key)
+  }
+}

package/server-managed/bundle-store.ts

@@ -0,0 +1,24 @@
+// Sourcemaps are stored once as Brotli. The DB retains the uploaded filename,
+// byte size and integrity so compression does not change report links/dedup.
+import type { Buffer } from 'node:buffer'
+import type { BlobStore, OpenedBlob } from './blob-store.ts'
+import { encodeBrotli } from './brotli.ts'
+
+export interface BundleStore {
+  put(id: string, bytes: Buffer, kind: string | null): Promise<string | null>
+  get(id: string, kind: string | null): Promise<Buffer | null>
+  open(id: string, kind: string | null): Promise<OpenedBlob | null>
+  delete(id: string): Promise<void>
+}
+
+export function createBundleStore(archives: BlobStore, sourcemaps: BlobStore): BundleStore {
+  const storage = (kind: string | null) => kind === 'sourcemap' ? sourcemaps : archives
+  return {
+    async put(id, bytes, kind) {
+      return storage(kind).put(id, kind === 'sourcemap' ? await encodeBrotli(bytes) : bytes)
+    },
+    get: (id, kind) => storage(kind).get(id),
+    open: (id, kind) => storage(kind).open(id),
+    async delete(id) { await Promise.all([archives.delete(id), sourcemaps.delete(id)]) },
+  }
+}

package/server-managed/bundle-summary-cache.ts

@@ -0,0 +1,130 @@
+import { Buffer } from 'node:buffer'
+import { setImmediate } from 'node:timers/promises'
+import { CacheMissError } from './cache-storage.ts'
+import { decodeUtf8 } from '../common/utf8.js'
+import { bundleCommitHash } from '../common/bundle-commit.js'
+import type { BundleCacheRecord, BundleCacheStorage, BundleSummary } from './bundle-cache.ts'
+
+// Version 3 adds the optional source commit; version 4 counts lines of code
+// without blank lines; version 5 adds a Stasis bundle's format version and
+// versioned package count. Older bundles use bounded backfill; until it
+// reaches one, catalogs serve its version 4 summary, which lacks only those.
+export const SUMMARY_FILENAME = 'v5-summary.json'
+const PREVIOUS_SUMMARY_FILENAME = 'v4-summary.json'
+const RETRY_MS = 5 * 60_000
+const BACKFILL_LIMIT = 4
+type CachedSummary = BundleSummary | { retryAt: number } | { previous: BundleSummary }
+
+async function readCurrentSummary(storage: BundleCacheStorage, id: string): Promise<CachedSummary> {
+  try { return await readSummary(storage, id, SUMMARY_FILENAME) }
+  catch (error) {
+    if (!(error instanceof CacheMissError)) throw error
+    const previous = await readSummary(storage, id, PREVIOUS_SUMMARY_FILENAME)
+    return 'retryAt' in previous ? previous : { previous }
+  }
+}
+
+async function readSummary(storage: BundleCacheStorage, id: string, file: string): Promise<BundleSummary | { retryAt: number }> {
+  const cached = await storage.open(id, file)
+  try {
+    const chunks: Buffer[] = []
+    let size = 0
+    for await (const chunk of cached.stream) {
+      size += chunk.length
+      if (size > 1024) throw new Error('Invalid bundle summary')
+      chunks.push(Buffer.from(chunk))
+    }
+    const summary = JSON.parse(decodeUtf8(Buffer.concat(chunks))) as BundleSummary | { retryAt: number }
+    if (summary && 'retryAt' in summary && Number.isSafeInteger(summary.retryAt) && summary.retryAt > 0) return summary
+    const counts = summary as BundleSummary
+    if (!counts || ![counts.files, counts.codeFiles, counts.lines].every(value => Number.isSafeInteger(value) && value >= 0)
+        || counts.codeFiles > counts.files || (counts.commit !== undefined && !bundleCommitHash(counts.commit))
+        || [counts.stasisVersion, counts.versionedPackages].some(value => value !== undefined && !(Number.isSafeInteger(value) && value >= 0))) throw new Error('Invalid bundle summary')
+    return counts
+  } finally { cached.stream.destroy() }
+}
+
+export function createBundleSummaryCache(storage: BundleCacheStorage, build: (record: BundleCacheRecord) => Promise<BundleSummary>, exists: (id: string) => Promise<unknown>) {
+  const entries = new Map<string, { id: string; value: CachedSummary }>()
+  const reads = new Map<string, { id: string; job: Promise<CachedSummary | null> }>()
+  const active = new Map<string, Promise<void>>()
+  let pending: Promise<void> | null = null
+  function remember(record: BundleCacheRecord, value: CachedSummary) {
+    // A completed build supersedes any older storage read still in flight.
+    reads.delete(record.integrity)
+    // Summaries are tiny and immutable by integrity. Refuse overflow admission
+    // instead of evicting the next hit during a scan larger than the cache.
+    if (entries.size >= 4096 && !entries.has(record.integrity)) return
+    entries.set(record.integrity, { id: record.id, value })
+  }
+  function read(record: BundleCacheRecord): Promise<CachedSummary | null> {
+    const known = entries.get(record.integrity)
+    if (known) return Promise.resolve(known.value)
+    const existing = reads.get(record.integrity)
+    if (existing) return existing.job
+    // Concurrent catalogs share the decoded summary, never the response stream.
+    // Only in-flight work is shared: misses and failures remain retryable.
+    const job: Promise<CachedSummary | null> = readCurrentSummary(storage, record.id).then(value => {
+      if (reads.get(record.integrity)?.job === job) remember(record, value)
+      return entries.get(record.integrity)?.value ?? value
+    }).catch(error => {
+      if (error instanceof CacheMissError) return null
+      throw error
+    }).finally(() => { if (reads.get(record.integrity)?.job === job) reads.delete(record.integrity) })
+    reads.set(record.integrity, { id: record.id, job })
+    return job
+  }
+  async function publish(record: BundleCacheRecord, value: CachedSummary) {
+    if (!await exists(record.id)) return
+    await storage.put(record.id, SUMMARY_FILENAME, Buffer.from(JSON.stringify(value)))
+    if (!await exists(record.id)) { await storage.delete(record.id); return }
+    remember(record, value)
+  }
+  async function buildOne(record: BundleCacheRecord) {
+    try { await publish(record, await build(record)) }
+    catch { await publish(record, { retryAt: Date.now() + RETRY_MS }).catch(() => {}) }
+  }
+  async function summaryStatus(record: BundleCacheRecord) {
+    const value = ['stasis', 'sourcemap'].includes(record.kind ?? '') ? await read(record) : null
+    return { summary: !value || 'retryAt' in value ? null : 'previous' in value ? value.previous : value,
+      summaryRetryAt: value && 'retryAt' in value ? value.retryAt : null }
+  }
+  async function backfill(records: readonly BundleCacheRecord[]) {
+    // Start after the catalog has been sent. Keep this work awaited by the
+    // request owner (including serverless), with no detached tasks or backlog.
+    await setImmediate()
+    let attempts = 0
+    for (const record of records) {
+      if (!['stasis', 'sourcemap'].includes(record.kind ?? '')) continue
+      const cached = await read(record).catch(() => null)
+      if (cached && !('previous' in cached) && (!('retryAt' in cached) || cached.retryAt > Date.now())) continue
+      if (!await exists(record.id)) continue
+      if (attempts++ >= BACKFILL_LIMIT) break
+      const job = buildOne(record)
+      active.set(record.id, job)
+      try { await job } finally { active.delete(record.id) }
+    }
+  }
+  return {
+    remember,
+    summaryStatus,
+    async summary(record: BundleCacheRecord): Promise<BundleSummary | null> {
+      return (await summaryStatus(record)).summary
+    },
+    backfill(records: readonly BundleCacheRecord[]) {
+      if (pending) return Promise.resolve() // Another catalog already owns the bounded batch.
+      const job = backfill(records).finally(() => { if (pending === job) pending = null })
+      pending = job
+      return job
+    },
+    async forget(id: string) {
+      // Only this bundle can republish its cache during deletion. A stalled
+      // backfill elsewhere must not delay removing these bytes or responding.
+      await active.get(id)
+      for (const [hash, entry] of entries) if (entry.id === id) entries.delete(hash)
+      // Do not wait for remote reads during deletion. Their callers still own
+      // and drain them, but a late response must not repopulate this cache.
+      for (const [hash, entry] of reads) if (entry.id === id) reads.delete(hash)
+    },
+  }
+}

package/server-managed/bundle.ts

@@ -0,0 +1,119 @@
+// Bundle helpers for the managed server: the content-addressed identity used to
+// dedupe stored bundles and to auto-link reports to them.
+//
+// A report's top-level `bundleHashes` lists the `sha512-<base64>` integrities
+// the analyzer ran against (see ui/view/ingest.js); a stored bundle's identity
+// is that same integrity computed from its bytes. Matching the two is how a
+// report auto-links to its bundle.
+import { createHash } from 'node:crypto'
+import type { Buffer } from 'node:buffer'
+import { StringDecoder } from 'node:string_decoder'
+import { brotliDecompress, createBrotliDecompress } from 'node:zlib'
+import { promisify } from 'node:util'
+import { parseBundleContents } from '../common/bundle-metadata.js'
+import { bundleFilesAsMap } from '../common/bundle-sources.js'
+import { commonFileDirectory } from '../common/managed/repository-alias.ts'
+import { decodeUtf8 } from '../common/utf8.js'
+
+// `sha512-<base64>` identity for a bundle's bytes. MUST stay byte-identical to
+// the client's common/integrity.js (SHA-512 → standard base64 WITH padding) so
+// a report's `bundleHashes` entries match a stored bundle's computed integrity.
+// (The client uses `Uint8Array.toBase64()`, whose default is standard base64 +
+// padding — the same bytes node:crypto's base64 digest emits.)
+export function bundleIntegrity(bytes: Buffer): string {
+  return `sha512-${createHash('sha512').update(bytes).digest('base64')}`
+}
+
+// Classify an uploaded bundle by filename — mirrors ui/view/ingest.js
+// `bundleKind`: sourcemap (.map) or stasis (stasis.code.br / .stasis.code.br).
+// null for anything else (stored anyway; the kind is informational).
+export function bundleKind(filename: string): 'sourcemap' | 'stasis' | null {
+  // Browsers insert a duplicate-download counter before the final extension.
+  const lower = filename.toLowerCase().replace(/ \(\d+\)(?=\.[^.]*$)/u, '')
+  if (lower.endsWith('.map')) return 'sourcemap'
+  if (lower === 'stasis.code.br' || lower.endsWith('.stasis.code.br')) return 'stasis'
+  return null
+}
+
+interface BundleRepo { github?: unknown; directory?: unknown }
+const HEADER_KEYS = new Set(['version', 'config', 'repo', 'package'])
+const MAX_HEADER_BYTES = 64 * 1024
+
+// Stasis writes origin metadata before entries, formats and source bodies.
+// undefined means another chunk is needed; null means the header has no repo.
+function headerRepo(text: string): BundleRepo | null | undefined {
+  let depth = 0, escaped = false, expectKey = false, quoted = false
+  let key = '', start = 0, valueStart = 0
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (quoted) {
+      if (escaped) { escaped = false; continue }
+      if (c === '\\') { escaped = true; continue }
+      if (c !== '"') continue
+      quoted = false
+      if (depth === 1 && expectKey) {
+        key = JSON.parse(text.slice(start, i + 1)) as string
+        if (!HEADER_KEYS.has(key)) return null
+        expectKey = false
+      }
+      continue
+    }
+    if (c === '"') { quoted = true; start = i; continue }
+    if (c === '{' || c === '[') {
+      if (depth === 0 && c !== '{') return null
+      depth++
+      if (depth === 1) expectKey = true
+    } else if (depth === 1 && (c === ',' || c === '}')) {
+      if (key === 'repo') {
+        const repo: unknown = JSON.parse(text.slice(valueStart, i))
+        return repo != null && typeof repo === 'object' && !Array.isArray(repo) ? repo as BundleRepo : null
+      }
+      if (c === '}') return null
+      expectKey = true
+    } else if (c === '}' || c === ']') depth--
+    else if (depth === 1 && c === ':') valueStart = i + 1
+    else if (depth === 0 && c?.trim()) return null
+  }
+  return undefined
+}
+
+// Decode only a bounded prefix, stopping as soon as repo is read or the
+// header ends. Unknown/malformed archives remain uploadable as opaque bytes.
+export async function bundleRepo(bytes: Buffer): Promise<BundleRepo | null> {
+  const stream = createBrotliDecompress({ chunkSize: 4096 })
+  const decoder = new StringDecoder('utf8')
+  let size = 0, text = ''
+  stream.end(bytes)
+  try {
+    for await (const chunk of stream) {
+      size += chunk.length
+      if (size > MAX_HEADER_BYTES) return null
+      text += decoder.write(chunk)
+      const repo = headerRepo(text)
+      if (repo !== undefined) return repo
+    }
+    return null
+  } catch { return null }
+  finally { stream.destroy() }
+}
+
+const decompress = promisify(brotliDecompress)
+// Same decoded size bound as the bundle metadata cache; only reached when an
+// alias can use a shared file suffix. Invalid/opaque bundles keep header defaults.
+export async function bundleFilePrefix(bytes: Buffer): Promise<string> {
+  try {
+    const decoded = await decompress(bytes, { maxOutputLength: 512 * 1024 * 1024 })
+    const details = parseBundleContents(decodeUtf8(decoded), { integrity: '', kind: 'stasis', size: bytes.length })
+    return commonFileDirectory(bundleFilesAsMap(details).keys())
+  } catch { return '' }
+}
+
+// Extract the bundle integrities a report declares (its top-level
+// `bundleHashes`), from the JSON it parsed to (readManagedReport's, as is).
+// Non-JSON reports (markdown / CSV, given as null) or a missing field → [].
+export function reportBundleHashes(data: unknown): string[] {
+  if (data == null || typeof data !== 'object') return []
+  const hashes = (data as { bundleHashes?: unknown }).bundleHashes
+  if (!Array.isArray(hashes)) return []
+  return hashes.filter((x): x is string => typeof x === 'string' && x !== '')
+}

package/server-managed/cache-storage.ts

@@ -0,0 +1,20 @@
+import type { Buffer } from 'node:buffer'
+import type { OpenedBlob } from './blob-store.ts'
+
+export class CacheMissError extends Error {
+  constructor() { super('Managed cache unavailable') }
+}
+
+// Keys are internal relative paths; delete removes a whole directory of
+// variants, but for one directory within it where `keep` names one.
+export interface CacheStorage {
+  exists(key: string): Promise<boolean>
+  put(key: string, bytes: Buffer): Promise<void>
+  open(key: string): Promise<OpenedBlob>
+  delete(prefix: string, keep?: string): Promise<void>
+}
+
+export function validateCacheKey(key: string): string {
+  if (!key.split('/').every(part => /^[a-z0-9][a-z0-9.-]*$/iu.test(part))) throw new Error('Invalid cache key')
+  return key
+}

package/server-managed/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Executable entry for the managed-server bin. See server-e2e/cli.js for the
+// full rationale: Node refuses to strip TypeScript types from files under
+// node_modules, so once this package is installed as a dependency
+// server-managed/index.ts can't be executed directly. Register the in-thread
+// type-stripping hook FIRST, then load the server via a dynamic import (a
+// static import would be fetched before the hook is active) and start it.
+//
+// Imported here rather than run as the process entry, so index.ts's
+// `import.meta.main` auto-start gate stays off and we call `start()` ourselves.
+import '../strip-types-loader.js'
+const command = process.argv[2]
+if (command === '--storage-encryption-status') {
+  const { storageCommand } = await import('./storage-command.ts')
+  await storageCommand(process.argv[3])
+} else if (command) {
+  throw new Error(`Unknown command: ${command}`)
+} else {
+  const { start } = await import('./index.ts')
+  await start()
+}

package/server-managed/combined.ts

@@ -0,0 +1,47 @@
+// Compose the existing HTTP apps on e2e's listener, including its WS/SSE
+// transports and static UI. Managed handles its API, discovery and page HTML;
+// assets and other requests fall through to the unchanged e2e HTTP handler.
+import { resolve } from 'node:path'
+import type { Server } from 'node:http'
+import { withReap } from '../server-common/reap.ts'
+import { loadConfig } from '../server-e2e/config.ts'
+import { createE2eApp } from '../server-e2e/app.ts'
+import { loadManagedConfig } from './config.ts'
+import { LOGIN_PATH } from './github-oauth.ts'
+import { createManagedApp, logManagedStartup } from './index.ts'
+
+export async function init(mode: 'managed+e2e' | 'e2e+managed', { ui = true }: { ui?: boolean } = {}): Promise<Server> {
+  const config = loadManagedConfig({ combined: true })
+  const e2eConfig = loadConfig()
+  if (!e2eConfig.neonUrl && !config.neonUrl && config.dbPath !== ':memory:' && resolve(config.dbPath) === resolve(e2eConfig.dbPath)) {
+    throw new Error('MANAGED_DB_PATH must differ from e2e DB_PATH in combined mode.')
+  }
+  const e2e = await createE2eApp(e2eConfig, { ui })
+  // Replace the assembled server's single
+  // request listener; adding a second would write two responses per request.
+  const handlers = e2e.httpServer.listeners('request')
+  const next = handlers[0]
+  if (handlers.length !== 1 || !next) throw new Error('Expected one e2e HTTP request handler')
+  const managed = await createManagedApp(config, {
+    next: e2e.handleRequest,
+    isShuttingDown: e2e.isShuttingDown,
+    ui,
+    serverInfo: {
+      mode, managed: { loginPath: LOGIN_PATH, cookieName: config.sessionCookieName },
+      ...(e2eConfig.deepviewScanServer ? { deepviewScanServer: e2eConfig.deepviewScanServer } : {}),
+    },
+  }).catch(async err => {
+    await e2e.httpServer[Symbol.asyncDispose]()
+    throw err
+  })
+  e2e.onShutdown(managed.close)
+  e2e.httpServer.removeListener('request', next)
+  e2e.httpServer.on('request', withReap(managed.handleRequest,
+    { e2e: e2e.reap, managed: managed.reap }, { isShuttingDown: e2e.isShuttingDown }))
+  e2e.httpServer.once('listening', () => {
+    const address = e2e.httpServer.address()
+    const port = typeof address === 'object' && address ? address.port : config.port
+    logManagedStartup(config, port, mode)
+  })
+  return e2e.httpServer
+}

package/server-managed/comments.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import { type ManagedComment, canDeleteComment } from '../common/managed/comments.ts'
+import type { ManagedSql } from './sql.ts'
+
+export interface CommentInput {
+  findingId: string
+  body: string
+  // Runtime imports may omit authorship, including future admin UI imports.
+  // Ordinary comment posts always supply the authenticated user as author.
+  authorId: string | null
+  authorLogin: string | null
+  // The user performing an import need not be the author of its comments.
+  // Omitted for ordinary posts, where the author is also the acting user.
+  actor?: { id: string; login: string }
+  // Omitted dates default to the action time; null preserves unknown dates.
+  createdAt?: number | null
+  updatedAt?: number | null
+  reportId?: string | null
+}
+
+export interface CommentStore {
+  listComments(findingIds: readonly string[]): Promise<ManagedComment[]>
+  listCommentedFindingIds(findingIds: readonly string[]): Promise<string[]>
+  getComment(id: string): Promise<ManagedComment | null>
+  createComment(input: CommentInput, now: number): Promise<ManagedComment>
+  editComment(id: string, authorId: string, authorLogin: string, body: string, version: number, reportId: string, now: number): Promise<ManagedComment | 'conflict' | 'forbidden' | null>
+  deleteComment(id: string, actorId: string, actorLogin: string, version: number, reportId: string, now: number): Promise<'deleted' | 'conflict' | 'forbidden' | null>
+}
+
+const COMMENT_COLUMNS = `id TEXT PRIMARY KEY, finding_id TEXT NOT NULL, body TEXT NOT NULL,
+  author_id TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  author_login TEXT, created_at INTEGER, updated_at INTEGER,
+  version INTEGER NOT NULL DEFAULT 1`
+
+export const COMMENT_SCHEMA = `
+    CREATE TABLE IF NOT EXISTS managed_finding_comment (${COMMENT_COLUMNS}) STRICT;
+    CREATE INDEX IF NOT EXISTS finding_comment_finding_idx ON managed_finding_comment(finding_id, created_at, id);
+    CREATE TABLE IF NOT EXISTS managed_finding_comment_event (
+      seq INTEGER PRIMARY KEY, comment_id TEXT NOT NULL, finding_id TEXT NOT NULL,
+      actor_id TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+      actor_login TEXT, action TEXT NOT NULL, at INTEGER NOT NULL,
+      report_id TEXT, report TEXT, repo TEXT
+    ) STRICT;
+    CREATE INDEX IF NOT EXISTS finding_comment_event_finding_idx ON managed_finding_comment_event(finding_id, seq);
+    CREATE INDEX IF NOT EXISTS finding_comment_event_actor_at_idx ON managed_finding_comment_event(actor_id, at);
+    CREATE INDEX IF NOT EXISTS finding_comment_event_at_idx ON managed_finding_comment_event(at, seq);
+`
+
+export function initCommentMethods(db: DatabaseSync): void {
+  db.exec(COMMENT_SCHEMA)
+  migrateCommentDates(db)
+  // updated_by belongs to the whole triage row, not necessarily its comment.
+  // Preserve legacy text without guessing an author. Clearing the old column
+  // in the same transaction makes the migration safe to restart. Use a fresh
+  // ID so a later legacy-server write cannot collide with an earlier import.
+  db.exec('BEGIN')
+  try {
+    db.exec(`INSERT INTO managed_finding_comment (id, finding_id, body, created_at, updated_at)
+      SELECT 'legacy:' || lower(hex(randomblob(16))), finding_id, comment, updated_at, updated_at
+      FROM managed_finding_triage WHERE comment IS NOT NULL AND comment != '';
+      UPDATE managed_finding_triage SET comment = NULL WHERE comment IS NOT NULL;`)
+    db.exec('COMMIT')
+  } catch (err) {
+    db.exec('ROLLBACK')
+    throw err
+  }
+}
+
+export function commentMethods(db: ManagedSql): CommentStore {
+  const fields = `c.id, c.finding_id AS findingId, c.body, c.author_id AS authorId,
+    COALESCE(u.login, c.author_login) AS authorLogin,
+    c.created_at AS createdAt, c.updated_at AS updatedAt, c.version`
+  const select = db.prepare(`SELECT ${fields} FROM managed_finding_comment c
+    LEFT JOIN managed_user u ON u.id = c.author_id WHERE c.id = ?`)
+  const list = db.prepare(`SELECT ${fields} FROM managed_finding_comment c
+    LEFT JOIN managed_user u ON u.id = c.author_id
+    WHERE c.finding_id IN (SELECT value FROM json_each(?)) ORDER BY c.created_at NULLS FIRST, c.id`)
+  const insert = db.prepare(`INSERT INTO managed_finding_comment
+    (id, finding_id, body, author_id, author_login, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+  const update = db.prepare(`UPDATE managed_finding_comment SET body = ?, updated_at = ?, version = version + 1
+    WHERE id = ? AND author_id = ? AND version = ?`)
+  const remove = db.prepare('DELETE FROM managed_finding_comment WHERE id = ? AND (author_id = ? OR (author_id IS NULL AND ? IS NULL)) AND version = ?')
+  const userRole = db.prepare('SELECT role FROM managed_user WHERE id = ?')
+  // Deleted comments still have audit events which explicit annotation purges
+  // must find, including when no current triage/comment record remains.
+  const annotated = db.prepare(`SELECT finding_id AS id FROM managed_finding_comment WHERE finding_id IN (SELECT value FROM json_each(?))
+    UNION SELECT finding_id AS id FROM managed_finding_comment_event WHERE finding_id IN (SELECT value FROM json_each(?))`)
+  const event = db.prepare(`INSERT INTO managed_finding_comment_event
+    (comment_id, finding_id, actor_id, actor_login, action, at, report_id, report, repo)
+    VALUES (?, ?, ?, ?, ?, ?, ?, (SELECT filename FROM managed_report WHERE id = ?),
+      (SELECT p.full_name FROM managed_report r JOIN managed_selected_repo p ON p.repo_id = r.repo_id WHERE r.id = ?))`)
+  const read = async (id: string) => (await select.get(id)) as ManagedComment | undefined
+  return {
+    async listComments(ids) { return ids.length > 0 ? (await list.all(JSON.stringify(ids))) as unknown as ManagedComment[] : [] },
+    async listCommentedFindingIds(ids) {
+      const json = JSON.stringify(ids)
+      return ((await annotated.all(json, json)) as { id: string }[]).map(row => row.id)
+    },
+    async getComment(id) { return (await read(id)) ?? null },
+    async createComment(input, now) {
+      const id = randomUUID()
+      const createdAt = input.createdAt === undefined ? now : input.createdAt
+      const updatedAt = input.updatedAt === undefined ? createdAt : input.updatedAt
+      await insert.run(id, input.findingId, input.body, input.authorId, input.authorLogin, createdAt, updatedAt)
+      await event.run(id, input.findingId, input.actor?.id ?? input.authorId, input.actor?.login ?? input.authorLogin, 'added a comment', now,
+        input.reportId ?? null, input.reportId ?? null, input.reportId ?? null)
+      return (await read(id))!
+    },
+    async editComment(id, authorId, authorLogin, body, version, reportId, now) {
+      // Identity/version checks and the event share the operation transaction.
+      const current = await read(id)
+      if (!current || current.authorId !== authorId || current.version !== version || current.body === body) {
+        if (!current) return null
+        if (current.authorId !== authorId) return 'forbidden'
+        if (current.version !== version) return 'conflict'
+        return current
+      }
+      await update.run(body, now, id, authorId, version)
+      await event.run(id, current.findingId, authorId, authorLogin, 'edited a comment', now, reportId, reportId, reportId)
+      return (await read(id))!
+    },
+    async deleteComment(id, actorId, actorLogin, version, reportId, now) {
+      const current = await read(id)
+      const role = (await userRole.get(actorId) as { role: string } | undefined)?.role ?? 'none'
+      const allowed = current != null && canDeleteComment(current, { id: actorId, role })
+      if (!current || !allowed || current.version !== version) {
+        if (!current) return null
+        return allowed ? 'conflict' : 'forbidden'
+      }
+      await remove.run(id, current.authorId, current.authorId, version)
+      await event.run(id, current.findingId, actorId, actorLogin, 'deleted a comment', now, reportId, reportId, reportId)
+      return 'deleted'
+    },
+  }
+}
+
+function migrateCommentDates(db: DatabaseSync): void {
+  const columns = db.prepare('PRAGMA table_info(managed_finding_comment)').all() as { name: string; notnull: number }[]
+  if (!columns.some(column => ['created_at', 'updated_at'].includes(column.name) && column.notnull)) return
+  db.exec('BEGIN')
+  try {
+    db.exec(`CREATE TABLE managed_finding_comment_nullable_dates (${COMMENT_COLUMNS}) STRICT;
+      INSERT INTO managed_finding_comment_nullable_dates (id, finding_id, body, author_id, author_login, created_at, updated_at, version)
+        SELECT id, finding_id, body, author_id, author_login, created_at, updated_at, version FROM managed_finding_comment;
+      DROP TABLE managed_finding_comment;
+      ALTER TABLE managed_finding_comment_nullable_dates RENAME TO managed_finding_comment;
+      CREATE INDEX finding_comment_finding_idx ON managed_finding_comment(finding_id, created_at, id);`)
+    db.exec('COMMIT')
+  } catch (err) { db.exec('ROLLBACK'); throw err }
+}