@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.30

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.30",
   "description": "Client & relay server for triaging of automated reports",
-  "license": "MIT",
+  "license": "MIT OR Apache-2.0",
   "author": {
     "name": "Nikita Skovoroda",
     "email": "chalkerx@gmail.com",
@@ -29,63 +29,198 @@
     "#client/sync-host.js": "./client/sync-host.js"
   },
   "exports": {
-    "./server": "./server/index.ts",
+    "./reap": "./api/reap.ts",
+    "./server": "./server.ts",
+    "./server-e2e": "./server-e2e/index.ts",
+    "./bundle-build-worker": "./server-managed/bundle-build-worker.js",
     "./strip-types-loader": "./strip-types-loader.js",
     "./package.json": "./package.json"
   },
   "bin": {
-    "triage-server": "server/cli.js"
+    "triage-server": "cli.js",
+    "triage-e2e-server": "server-e2e/cli.js",
+    "triage-managed-server": "server-managed/cli.js"
   },
   "files": [
-    "server/auth.ts",
-    "server/bus-receiver.ts",
-    "server/cli.js",
-    "server/config.ts",
-    "server/db-neon.ts",
-    "server/db-revision-sql.ts",
-    "server/db-stmt.ts",
-    "server/db.ts",
-    "server/http.ts",
-    "server/hub.ts",
-    "server/index.ts",
-    "server/lifecycle.ts",
-    "server/neon-driver.ts",
-    "server/npm-proxy.ts",
-    "server/objstore/blob-fs.ts",
-    "server/objstore/blob-vercel.ts",
-    "server/objstore/blob.ts",
-    "server/objstore/fs.ts",
-    "server/objstore/handlers.ts",
-    "server/objstore/init.ts",
-    "server/objstore/reaper.ts",
-    "server/objstore/rest.ts",
-    "server/objstore/sign.ts",
-    "server/objstore/store-neon.ts",
-    "server/objstore/store.ts",
-    "server/objstore/tokens.ts",
-    "server/origin.ts",
-    "server/peer.ts",
-    "server/pubsub.ts",
-    "server/sign.ts",
-    "server/sse-server.ts",
-    "server/sse-session.ts",
-    "server/static.ts",
-    "server/sync-handlers.ts",
-    "server/util.ts",
-    "server/validation.ts",
-    "server/ws-server.ts",
-    "server/config.example.json",
+    "LICENSE-APACHE",
+    "LICENSE-MIT",
+    "api/reap.ts",
+    "cli.js",
+    "server.ts",
+    "server-e2e/app.ts",
+    "server-e2e/auth.ts",
+    "server-e2e/bus-receiver.ts",
+    "server-e2e/cli.js",
+    "server-e2e/config.ts",
+    "server-e2e/db-neon.ts",
+    "server-e2e/db-revision-sql.ts",
+    "server-e2e/db-stmt.ts",
+    "server-e2e/db.ts",
+    "server-e2e/http.ts",
+    "server-e2e/hub.ts",
+    "server-e2e/index.ts",
+    "server-e2e/lifecycle.ts",
+    "server-e2e/neon-driver.ts",
+    "server-e2e/npm-proxy.ts",
+    "server-e2e/objstore/blob-fs.ts",
+    "server-e2e/objstore/blob-vercel.ts",
+    "server-e2e/objstore/blob.ts",
+    "server-e2e/objstore/fetch-mint-guard.ts",
+    "server-e2e/objstore/fs.ts",
+    "server-e2e/objstore/handlers.ts",
+    "server-e2e/objstore/init.ts",
+    "server-e2e/objstore/reaper.ts",
+    "server-e2e/objstore/rest-deny.ts",
+    "server-e2e/objstore/rest-mint.ts",
+    "server-e2e/objstore/rest.ts",
+    "server-e2e/objstore/sign.ts",
+    "server-e2e/objstore/store-neon.ts",
+    "server-e2e/objstore/store.ts",
+    "server-e2e/objstore/tokens.ts",
+    "server-e2e/peer.ts",
+    "server-e2e/pubsub.ts",
+    "server-e2e/sign.ts",
+    "server-e2e/sse-server.ts",
+    "server-e2e/sse-session.ts",
+    "server-e2e/static.ts",
+    "server-e2e/sync-handlers.ts",
+    "server-e2e/util.ts",
+    "server-e2e/validation.ts",
+    "server-e2e/ws-server.ts",
+    "server-e2e/config.example.json",
+    "server-managed/activity.ts",
+    "server-managed/avatar-store.ts",
+    "server-managed/blob-store.ts",
+    "server-managed/brotli.ts",
+    "server-managed/bundle-advisories.ts",
+    "server-managed/bundle-advisory-inventory.ts",
+    "server-managed/bundle-cache.ts",
+    "server-managed/bundle-build.ts",
+    "server-managed/bundle-build-leases.ts",
+    "server-managed/bundle-build-worker.js",
+    "server-managed/bundle-build-diagnostics.js",
+    "server-managed/bundle-build-diagnostics.d.ts",
+    "server-managed/bundle-catalog.ts",
+    "server-managed/bundle-store.ts",
+    "server-managed/bundle-summary-cache.ts",
+    "server-managed/bundle.ts",
+    "server-managed/cache-storage.ts",
+    "server-managed/cli.js",
+    "server-managed/combined.ts",
+    "server-managed/comments.ts",
+    "server-managed/config.ts",
+    "server-managed/content-access.ts",
+    "server-managed/crypto.ts",
+    "server-managed/db-methods.ts",
+    "server-managed/db-neon.ts",
+    "server-managed/db-schema.ts",
+    "server-managed/db-table-names.ts",
+    "server-managed/db.ts",
+    "server-managed/github-app.ts",
+    "server-managed/github-errors.ts",
+    "server-managed/github-metadata.ts",
+    "server-managed/github-issue-oauth.ts",
+    "server-managed/github-issues.ts",
+    "server-managed/github-oauth.ts",
+    "server-managed/github-pulls.ts",
+    "server-managed/http-response.ts",
+    "server-managed/http.ts",
+    "server-managed/import-triage.ts",
+    "server-managed/managed-issues.ts",
+    "server-managed/management.ts",
+    "server-managed/management-catalog.ts",
+    "server-managed/object-storage.ts",
+    "server-managed/object-storage-disk.ts",
+    "server-managed/object-storage-vercel.ts",
+    "server-managed/index.ts",
+    "server-managed/package-entry-points.ts",
+    "server-managed/public-workspace.ts",
+    "server-managed/repo-path.ts",
+    "server-managed/report-migration.ts",
+    "server-managed/report-query.ts",
+    "server-managed/report-response.ts",
+    "server-managed/report-sources.ts",
+    "server-managed/revisions.ts",
+    "server-managed/repository-browser.ts",
+    "server-managed/repository-discovery.ts",
+    "server-managed/repository-policy.ts",
+    "server-managed/session.ts",
+    "server-managed/slugs.ts",
+    "server-managed/solidity-entry-points.ts",
+    "server-managed/sql-postgres.ts",
+    "server-managed/sql.ts",
+    "server-managed/static.ts",
+    "server-managed/storage.ts",
+    "server-managed/storage-command.ts",
+    "server-managed/storage-db.ts",
+    "server-managed/storage-encryption.ts",
+    "server-managed/storage-maintenance.ts",
+    "server-managed/storage-payload.ts",
+    "server-managed/storage-stores.ts",
+    "server-managed/team-catalog.ts",
+    "server-managed/team-feed.ts",
+    "server-managed/team-reports.ts",
+    "server-managed/triage-response.ts",
+    "server-managed/uploads.ts",
+    "server-managed/workspace-shares.ts",
+    "server-common/database-config.ts",
+    "server-common/initialize.ts",
+    "server-common/reap.ts",
+    "server-common/npm-advisories.ts",
+    "server-common/origin.ts",
+    "server-common/standalone.ts",
+    "server-common/storage-log.ts",
+    "server-common/storage-crypto.ts",
+    "server-common/vercel-blob.ts",
+    "server-common/scan-config.ts",
+    "common/bundle-commit.d.ts",
+    "common/bundle-commit.js",
+    "common/bundle-metadata.d.ts",
+    "common/bundle-metadata.js",
+    "common/bundle-reasons.d.ts",
+    "common/bundle-reasons.js",
+    "common/bundle-sources.d.ts",
+    "common/bundle-sources.js",
+    "common/bundle-source-links.d.ts",
+    "common/bundle-source-links.js",
+    "common/bundle-stats.js",
+    "common/bundle-tabs.js",
+    "common/code-language.js",
+    "common/default-scan-models.ts",
+    "common/finding-id.js",
+    "common/github-pr.ts",
+    "common/github-issue-labels.js",
+    "common/github-issue-labels.d.ts",
+    "common/managed/comments.ts",
+    "common/managed/permissions.ts",
+    "common/managed/report-content.ts",
+    "common/managed/report-filter.ts",
+    "common/managed/roles.ts",
+    "common/managed/routes.d.ts",
+    "common/managed/routes.js",
+    "common/managed/scan-models.ts",
+    "common/managed/triage.ts",
     "common/save-error-reason.ts",
+    "common/server-info.ts",
+    "common/scan-server.ts",
     "common/utf8.d.ts",
     "common/utf8.js",
+    "client/finding-link.js",
+    "client/linked-findings.d.ts",
+    "client/linked-findings.js",
     "out/brotli-fallback.js",
+    "out/client-managed.js",
+    "out/client-managed-import.js",
     "out/client-sync.js",
     "out/graph.js",
+    "out/github-issue-authorized.html",
+    "out/github-issue-authorized.js",
     "out/icon-maskable.svg",
     "out/icon.svg",
     "out/index.html",
     "out/manifest.webmanifest",
     "out/prism.js",
+    "out/stasis.svg",
     "out/terminal.js",
     "out/view.css",
     "out/view.html",
@@ -94,40 +229,50 @@
   ],
   "scripts": {
     "lint": "node --run lint:js && node --run lint:css && node --run lint:ts",
-    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./tests/ ./common/ ./server/ ./client/ ./ui/",
+    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./cli.js ./server.ts ./tests/ ./common/ ./server-common/ ./server-e2e/ ./server-managed/ ./client/ ./ui/ ./api/",
     "lint:css": "stylelint 'ui/**/*.css'",
     "lint:ts": "tsc --noEmit",
     "prepack": "node --run build",
     "build": "node build.js build",
     "serve": "node build.js serve",
-    "server": "node server/index.ts",
-    "test": "node --js-base-64 --experimental-test-module-mocks --test ./tests/*.test.js"
+    "server": "node --run server-e2e --",
+    "server-e2e": "node server-e2e/index.ts",
+    "server-managed": "node server-managed/index.ts",
+    "server-managed-test": "node server-managed/test-server.ts",
+    "test": "node --js-base-64 --import=./tests/_resource-loader.js --experimental-test-module-mocks --test-timeout=120000 --test ./tests/*.test.js"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.4.5",
-    "@exodus/stasis": "^1.0.0-alpha.1",
-    "@noble/ciphers": "^2.2.0",
-    "@preventive/terminal": "^1.3.0",
+    "@electric-sql/pglite": "^0.5.5",
+    "@noble/ciphers": "^2.3.0",
+    "@preventive/diff": "^1.0.0",
+    "@preventive/lockfile": "1.0.0-alpha.5",
+    "@preventive/terminal": "2.0.0-beta.1",
     "@rray/frontend": "^1.0.0",
-    "@stylistic/stylelint-plugin": "^5.1.0",
-    "@types/node": "^25.6.2",
+    "@stylistic/stylelint-plugin": "^5.3.0",
+    "@types/node": "^26.2.0",
     "@types/ws": "^8.18.1",
+    "@vercel/functions": "^3.9.11",
     "brotli": "^1.3.3",
-    "esbuild": "^0.27.4",
-    "lit": "^3.3.2",
+    "esbuild": "^0.28.2",
+    "lit": "^3.3.3",
     "minify-html-literals": "^1.3.5",
-    "oxlint": "^1.63.0",
+    "oxlint": "^1.79.0",
     "prismjs": "^1.30.0",
-    "stylelint": "^17.11.0",
+    "stylelint": "^17.14.1",
     "stylelint-config-recommended": "^18.0.0",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "dependencies": {
+    "@exodus/stasis": "1.0.0-beta.5",
+    "@exodus/stasis-core": "1.0.0-beta.5",
+    "@preventive/report": "1.0.0-alpha.4",
+    "@preventive/upstream": "1.0.0-alpha.4",
     "ws": "^8.20.1"
   },
   "peerDependencies": {
     "@neondatabase/serverless": "^1.0.2",
-    "@vercel/blob": "^2.3.3"
+    "@vercel/blob": "^2.3.3",
+    "@vercel/functions": "^3.9.11"
   },
   "peerDependenciesMeta": {
     "@neondatabase/serverless": {
@@ -135,6 +280,9 @@
     },
     "@vercel/blob": {
       "optional": true
+    },
+    "@vercel/functions": {
+      "optional": true
     }
   },
   "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800"

package/server-common/database-config.ts

@@ -0,0 +1,16 @@
+import { env } from 'node:process'
+
+// One shared URL or per-mode URLs. Validate before opening either store so
+// an ambiguous configuration cannot send application traffic and GC elsewhere.
+export function databaseUrls({ combined = false } = {}) {
+  const shared = env['DATABASE_URL'] || null
+  const e2e = env['E2E_DATABASE_URL'] || null
+  const managed = env['MANAGED_DATABASE_URL'] || null
+  if (shared && (e2e || managed)) {
+    throw new Error('DATABASE_URL cannot be combined with E2E_DATABASE_URL or MANAGED_DATABASE_URL. Use the shared URL alone, or only the per-mode URLs.')
+  }
+  if (combined && Boolean(e2e) !== Boolean(managed)) {
+    throw new Error('Combined mode requires both E2E_DATABASE_URL and MANAGED_DATABASE_URL, DATABASE_URL alone, or no database URLs. Mixing Neon and SQLite is not supported.')
+  }
+  return { e2e: shared ?? e2e, managed: shared ?? managed }
+}

package/server-common/initialize.ts

@@ -0,0 +1,18 @@
+// Register resources as they are acquired. Failed assembly rolls them back in
+// reverse order; successful assembly transfers ownership to the returned app.
+export async function initializeApp<T>(assemble: (rollback: AsyncDisposableStack) => T | Promise<T>): Promise<T> {
+  const rollback = new AsyncDisposableStack()
+  try {
+    const app = await assemble(rollback)
+    rollback.move()
+    return app
+  } catch (error) {
+    try { await rollback.disposeAsync() }
+    catch (cleanupError) {
+      // AsyncDisposableStack runs every cleanup even if one fails. Preserve
+      // both failures so cleanup errors cannot hide the initialization error.
+      throw new SuppressedError(cleanupError, error, 'App initialization and cleanup failed')
+    }
+    throw error
+  }
+}

package/server-common/npm-advisories.ts

@@ -0,0 +1,101 @@
+import { Buffer } from 'node:buffer'
+
+const UPSTREAM_URL = 'https://registry.npmjs.org/-/npm/v1/security/advisories/bulk'
+const RESPONSE_BODY_LIMIT = 4 * 1024 * 1024
+export const NPM_ADVISORIES_TIMEOUT_MS = 30_000
+
+export async function fetchNpmAdvisories(body: Buffer, signal: AbortSignal, debug = false): Promise<{ status: number; body: unknown }> {
+  let upstream: Response
+  try {
+    upstream = await fetch(UPSTREAM_URL, {
+      method: 'POST',
+      // Force JSON — the bulk endpoint requires it. Drop every
+      // client-supplied header to keep an upstream fingerprint from
+      // leaking through (cookies, auth, custom UA, ...). The
+      // registry's bulk endpoint doesn't need any of them for a
+      // public lookup.
+      headers: { 'content-type': 'application/json', 'accept': 'application/json' },
+      // Re-wrap as a plain Uint8Array — Buffer's underlying
+      // ArrayBufferLike type doesn't satisfy fetch's BodyInit
+      // narrowing (it can't statically rule out SharedArrayBuffer),
+      // but a copy through Uint8Array is zero-cost in practice and
+      // unambiguously typed.
+      body: new Uint8Array(body),
+      signal,
+    })
+  } catch (err: unknown) {
+    if (debug) console.warn('npm-advisories upstream error:', err)
+    return { status: 502, body: { error: 'upstream-unreachable' } }
+  }
+  // Assert JSON on the upstream body. The Content-Type header is
+  // unreliable (Cloudflare in front of registry.npmjs.org strips it
+  // from some responses; a captive portal / WAF can declare HTML on
+  // a body that's actually JSON or vice-versa), so we don't lean on
+  // it — instead we buffer the body and parse. A successful
+  // JSON.parse is the strongest guarantee we can hand the UI's
+  // `await res.json()`. Buffering is bounded by
+  // `RESPONSE_BODY_LIMIT`; the advisories endpoint's payloads sit
+  // well under that.
+  const upstreamContentType = upstream.headers.get('content-type') ?? ''
+  let buffered: Buffer | null
+  try {
+    buffered = await readUpstreamBody(upstream)
+  } catch (err: unknown) {
+    if (debug) console.warn('npm-advisories upstream body error:', err)
+    return { status: 502, body: { error: 'upstream-unreachable' } }
+  }
+  if (buffered === null) {
+    if (debug) console.warn(`npm-advisories upstream too large: status=${upstream.status}`)
+    return { status: 502, body: { error: 'upstream-too-large', upstreamStatus: upstream.status } }
+  }
+  // Treat the body as UTF-8 — `JSON.parse` operates on a string and
+  // the registry's responses are always UTF-8 in practice. A
+  // non-UTF-8 byte sequence still decodes (with U+FFFD
+  // substitution); the subsequent JSON.parse fails and routes
+  // through the error branch.
+  const text = buffered.toString('utf8')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    if (debug) console.warn(`npm-advisories upstream non-JSON: status=${upstream.status} ct=${upstreamContentType || '<none>'} bytes=${buffered.byteLength}`)
+    return { status: 502, body: {
+      error: 'upstream-not-json',
+      upstreamStatus: upstream.status,
+      upstreamContentType: upstreamContentType || null,
+    } }
+  }
+  return { status: upstream.status, body: parsed }
+}
+
+// Buffer the upstream response body up to RESPONSE_BODY_LIMIT.
+// Returns null if the cap is exceeded (caller maps to a 502
+// `upstream-too-large`), or the cumulative Buffer otherwise. A
+// transport error mid-read (e.g. AbortSignal fired by the deadline
+// timer or by `req` close) throws — the caller catches it.
+//
+// `finally { reader.cancel() }` is load-bearing on the error and
+// cap-exceeded paths: leaving the reader locked to the body holds
+// the underlying undici TCP socket out of the connection pool until
+// GC, and the cap-exceeded path explicitly needs to tear the
+// transfer down so we don't keep buffering bytes we'll never use.
+// On the clean-drain path (done:true), cancel() is a no-op.
+async function readUpstreamBody(upstream: Response): Promise<Buffer | null> {
+  if (!upstream.body) return Buffer.alloc(0)
+  const reader = upstream.body.getReader()
+  const chunks: Uint8Array[] = []
+  let received = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (!value) continue
+      received += value.byteLength
+      if (received > RESPONSE_BODY_LIMIT) return null
+      chunks.push(value)
+    }
+    return Buffer.concat(chunks)
+  } finally {
+    try { await reader.cancel() } catch {}
+  }
+}

package/{server → server-common}/origin.ts

@@ -1,8 +1,8 @@
-// Same-origin gate for the WS upgrade and REST data plane. We don't
-// support cross-origin browser clients, so any Origin header present
-// on an incoming request MUST match the server's own host (derived
-// from `req.headers.host`, or from `X-Forwarded-Host` /
-// `X-Forwarded-Proto` when a trusted reverse proxy is in front).
+// Same-origin gate, shared by the e2e and managed servers (server-common).
+// We don't support cross-origin browser clients, so any Origin header present
+// on an incoming request MUST match the server's own host (derived from
+// `req.headers.host`, or from `X-Forwarded-Host` / `X-Forwarded-Proto` when a
+// trusted reverse proxy is in front).
 //
 // Why "present-must-match" rather than "always required":
 // - Browser WebSocket handshakes always carry Origin (RFC 6455), so a

package/server-common/reap.ts

@@ -0,0 +1,48 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+type Handler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+type Reapers = Record<string, () => Promise<unknown>>
+type Options = { secret?: string; isShuttingDown?: () => boolean }
+
+// Start every cleanup and wait for all of them, including when one fails.
+// The caller must not close storage or return success with work still running.
+export async function runReapers(reapers: Reapers): Promise<void> {
+  const results = await Promise.allSettled(Object.values(reapers).map(reap => Promise.resolve().then(reap)))
+  const errors = results.filter(result => result.status === 'rejected').map(result => result.reason)
+  if (errors.length > 0) throw new AggregateError(errors, 'Cleanup failed')
+}
+
+export function createReapHandler(reapers: Reapers, { secret = process.env['CRON_SECRET'], isShuttingDown = () => false }: Options = {}) {
+  const key = randomBytes(32)
+  const hash = (value: string) => createHmac('sha256', key).update(value).digest()
+  const expected = secret ? hash(`Bearer ${secret}`) : null
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const send = (status: number, body: object, headers = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers })
+      res.end(JSON.stringify(body))
+    }
+    const authorization = req.headers.authorization
+    if (req.headers['x-deepview-share'] !== undefined) { send(403, { error: 'share-scope-required' }); return }
+    if (!expected || typeof authorization !== 'string' || !timingSafeEqual(hash(authorization), expected)) {
+      send(401, { error: 'unauthorized' }); return
+    }
+    if (req.method !== 'GET') { send(405, { error: 'method-not-allowed' }, { allow: 'GET' }); return }
+    if (isShuttingDown()) { send(503, { error: 'shutting-down' }); return }
+    const startedAt = Date.now()
+    try {
+      await runReapers(reapers)
+      send(200, { ok: true, reaped: Object.keys(reapers), ms: Date.now() - startedAt })
+    } catch (err) {
+      console.error('reap failed:', err)
+      send(500, { error: 'reap-failed' })
+    }
+  }
+}
+
+// Only top-level servers compose this route. Domain routers stay unaware of
+// other modes, and cleanup uses the stores those servers have already opened.
+export function withReap(next: Handler, reapers: Reapers, options: Options = {}): Handler {
+  const reap = createReapHandler(reapers, options)
+  return (req, res) => req.url?.split('?', 1)[0] === '/api/reap' ? reap(req, res) : next(req, res)
+}

package/server-common/scan-config.ts

@@ -0,0 +1,19 @@
+import { normalizeScanServer } from '../common/scan-server.ts'
+
+export function configuredScanServer(value: string | undefined): string | null {
+  if (!value?.trim()) return null
+  const server = normalizeScanServer(value)
+  if (!server) throw new Error('DEEPVIEW_SCAN_SERVER must be an absolute HTTP(S) URL without credentials, query, or fragment')
+  return server
+}
+
+// Apply at serve time, before compression and ETag generation. Packaged HTML
+// stays strict and does not bake in the build machine's configuration.
+export function scanServerHtml(html: string, server: string | null, { advertise = false } = {}): string {
+  if (!server) return html
+  const origin = new URL(server).origin
+  const result = html.replace(/(connect-src 'self')(?=[;"])/u, `$1 ${origin}`)
+  if (!advertise) return result
+  const content = server.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')
+  return result.replace('</head>', `<meta name="deepview-scan-server" content="${content}">\n</head>`)
+}

package/server-common/standalone.ts

@@ -0,0 +1,29 @@
+import type { Server } from 'node:http'
+
+// Only CLI entry points own process signals and termination. Embedded servers
+// expose async disposal and error events to their host instead.
+export function startServer(server: Server, config: { port: number; host: string }): void {
+  let shuttingDown = false
+  let exitCode = 0
+  function shutdown(code: number): void {
+    if (code !== 0) exitCode = code
+    if (shuttingDown) return
+    shuttingDown = true
+    console.log('Shutting down…')
+    void server[Symbol.asyncDispose]().catch(err => {
+      console.error('Shutdown failed:', err)
+      exitCode = 1
+    }).finally(() => process.exit(exitCode))
+  }
+  function onSignal(): void { shutdown(0) }
+  function onError(err: unknown): void {
+    console.error('Server error:', err)
+    shutdown(1)
+  }
+  server.on('error', onError)
+  process.on('SIGINT', onSignal)
+  process.on('SIGTERM', onSignal)
+  process.on('unhandledRejection', onError)
+  process.on('uncaughtException', onError)
+  server.listen(config.port, config.host)
+}