airaknit 1.1.2-rc.9

package/src/server/cli-runtime.ts

@@ -0,0 +1,374 @@
+import process from "node:process"
+import { spawnSync } from "node:child_process"
+import { hasCommand, spawnDetached } from "./process-utils"
+import { APP_NAME, CLI_COMMAND, getDataDirDisplay, LOG_PREFIX, PACKAGE_NAME } from "../shared/branding"
+import type { UpdateInstallErrorCode } from "../shared/types"
+import { PROD_SERVER_PORT } from "../shared/ports"
+import { CLI_SUPPRESS_OPEN_ONCE_ENV_VAR } from "./restart"
+import { logShareDetails, renderTerminalQr, startShareTunnel, type StartedShareTunnel } from "./share"
+
+export interface CliOptions {
+  port: number
+  host: string
+  openBrowser: boolean
+  share: boolean
+  strictPort: boolean
+  sandbox: boolean
+}
+
+export interface CliUpdateOptions {
+  version: string
+  fetchLatestVersion: (packageName: string) => Promise<string>
+  installVersion: (packageName: string, version: string) => UpdateInstallAttemptResult
+  argv: string[]
+  command: string
+}
+
+export interface StartedCli {
+  kind: "started"
+  stop: () => Promise<void>
+}
+
+export interface RestartingCli {
+  kind: "restarting"
+  reason: "startup_update" | "ui_update"
+}
+
+export interface ExitedCli {
+  kind: "exited"
+  code: number
+}
+
+export type CliRunResult = StartedCli | RestartingCli | ExitedCli
+
+export interface CliRuntimeDeps {
+  version: string
+  bunVersion: string
+  startServer: (options: CliOptions & {
+    update: CliUpdateOptions
+    onMigrationProgress?: (message: string) => void
+  }) => Promise<{ port: number; stop: () => Promise<void> }>
+  fetchLatestVersion: (packageName: string) => Promise<string>
+  installVersion: (packageName: string, version: string) => UpdateInstallAttemptResult
+  openUrl: (url: string) => void
+  log: (message: string) => void
+  warn: (message: string) => void
+  renderShareQr?: (url: string) => Promise<string>
+  startShareTunnel?: (localUrl: string) => Promise<StartedShareTunnel>
+}
+
+export interface UpdateInstallAttemptResult {
+  ok: boolean
+  errorCode: UpdateInstallErrorCode | null
+  userTitle: string | null
+  userMessage: string | null
+}
+
+type ParsedArgs =
+  | { kind: "run"; options: CliOptions }
+  | { kind: "help" }
+  | { kind: "version" }
+
+const MINIMUM_BUN_VERSION = "1.3.5"
+
+function printHelp() {
+  console.log(`${APP_NAME} — local-only project chat UI
+
+Usage:
+  ${CLI_COMMAND} [options]
+
+Options:
+  --port <number>      Port to listen on (default: ${PROD_SERVER_PORT})
+  --host <host>        Bind to a specific host or IP
+  --remote             Shortcut for --host 0.0.0.0
+  --share              Create a public Cloudflare share URL with terminal QR
+  --strict-port        Fail instead of trying another port
+  --no-open            Don't open browser automatically
+  --sandbox            Enable Docker sandbox isolation for workspaces
+  --version            Print version and exit
+  --help               Show this help message`)
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  let port = PROD_SERVER_PORT
+  let host = "127.0.0.1"
+  let openBrowser = true
+  let share = false
+  let sawHost = false
+  let sawRemote = false
+  let strictPort = false
+  let sandbox = false
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === "--version" || arg === "-v") {
+      return { kind: "version" }
+    }
+    if (arg === "--help" || arg === "-h") {
+      return { kind: "help" }
+    }
+    if (arg === "--port") {
+      const next = argv[index + 1]
+      if (!next) throw new Error("Missing value for --port")
+      const parsed = Number(next)
+      if (!Number.isFinite(parsed)) throw new Error(`Invalid port: ${next}`)
+      port = parsed
+      index += 1
+      continue
+    }
+    if (arg === "--host") {
+      const next = argv[index + 1]
+      if (!next || next.startsWith("-")) throw new Error("Missing value for --host")
+      if (share) throw new Error("--share cannot be used with --host")
+      host = next
+      sawHost = true
+      index += 1
+      continue
+    }
+    if (arg === "--remote") {
+      if (share) throw new Error("--share cannot be used with --remote")
+      host = "0.0.0.0"
+      sawRemote = true
+      continue
+    }
+    if (arg === "--share") {
+      if (sawHost) throw new Error("--share cannot be used with --host")
+      if (sawRemote) throw new Error("--share cannot be used with --remote")
+      share = true
+      continue
+    }
+    if (arg === "--no-open") {
+      openBrowser = false
+      continue
+    }
+    if (arg === "--strict-port") {
+      strictPort = true
+      continue
+    }
+    if (arg === "--sandbox") {
+      sandbox = true
+      continue
+    }
+    if (!arg.startsWith("-")) throw new Error(`Unexpected positional argument: ${arg}`)
+  }
+
+  return {
+    kind: "run",
+    options: {
+      port,
+      host,
+      openBrowser,
+      share,
+      strictPort,
+      sandbox,
+    },
+  }
+}
+
+export function compareVersions(currentVersion: string, latestVersion: string) {
+  const currentParts = normalizeVersion(currentVersion)
+  const latestParts = normalizeVersion(latestVersion)
+  const length = Math.max(currentParts.length, latestParts.length)
+
+  for (let index = 0; index < length; index += 1) {
+    const current = currentParts[index] ?? 0
+    const latest = latestParts[index] ?? 0
+    if (current === latest) continue
+    return current < latest ? -1 : 1
+  }
+
+  return 0
+}
+
+function normalizeVersion(version: string) {
+  return version
+    .trim()
+    .replace(/^v/i, "")
+    .split("-")[0]
+    .split(".")
+    .map((part) => Number.parseInt(part, 10))
+    .filter((part) => Number.isFinite(part))
+}
+
+async function maybeSelfUpdate(_argv: string[], deps: CliRuntimeDeps) {
+  if (process.env.KANNA_DISABLE_SELF_UPDATE === "1") {
+    return null
+  }
+
+  deps.log(`${LOG_PREFIX} checking for updates`)
+
+  let latestVersion: string
+  try {
+    latestVersion = await deps.fetchLatestVersion(PACKAGE_NAME)
+  }
+  catch (error) {
+    deps.warn(`${LOG_PREFIX} update check failed, continuing current version`)
+    if (error instanceof Error && error.message) {
+      deps.warn(`${LOG_PREFIX} ${error.message}`)
+    }
+    return null
+  }
+
+  if (!latestVersion || compareVersions(deps.version, latestVersion) >= 0) {
+    return null
+  }
+
+  deps.log(`${LOG_PREFIX} installing ${PACKAGE_NAME}@${latestVersion}`)
+  const installResult = deps.installVersion(PACKAGE_NAME, latestVersion)
+  if (!installResult.ok) {
+    deps.warn(`${LOG_PREFIX} update failed, continuing current version`)
+    if (installResult.userMessage) {
+      deps.warn(`${LOG_PREFIX} ${installResult.userMessage}`)
+    }
+    return null
+  }
+
+  deps.log(`${LOG_PREFIX} restarting into updated version`)
+  return "startup_update"
+}
+
+export async function runCli(argv: string[], deps: CliRuntimeDeps): Promise<CliRunResult> {
+  const parsedArgs = parseArgs(argv)
+  if (parsedArgs.kind === "version") {
+    deps.log(deps.version)
+    return { kind: "exited", code: 0 }
+  }
+  if (parsedArgs.kind === "help") {
+    printHelp()
+    return { kind: "exited", code: 0 }
+  }
+
+  if (compareVersions(deps.bunVersion, MINIMUM_BUN_VERSION) < 0) {
+    deps.warn(`${LOG_PREFIX} Bun ${MINIMUM_BUN_VERSION}+ is required for the embedded terminal. Current Bun: ${deps.bunVersion}`)
+    return { kind: "exited", code: 1 }
+  }
+
+  const shouldRestart = await maybeSelfUpdate(argv, deps)
+  if (shouldRestart !== null) {
+    return { kind: "restarting", reason: shouldRestart }
+  }
+
+  const { port, stop } = await deps.startServer({
+    ...parsedArgs.options,
+    onMigrationProgress: deps.log,
+    update: {
+      version: deps.version,
+      fetchLatestVersion: deps.fetchLatestVersion,
+      installVersion: deps.installVersion,
+      argv,
+      command: CLI_COMMAND,
+    },
+  })
+  const bindHost = parsedArgs.options.host
+  const displayHost = parsedArgs.options.share || bindHost === "127.0.0.1" || bindHost === "0.0.0.0" ? "localhost" : bindHost
+  const launchUrl = `http://${displayHost}:${port}`
+  let shareTunnelStop: (() => void) | null = null
+
+  deps.log(`${LOG_PREFIX} listening on http://${bindHost}:${port}`)
+  deps.log(`${LOG_PREFIX} data dir: ${getDataDirDisplay()}`)
+
+  const suppressOpenBrowser = process.env[CLI_SUPPRESS_OPEN_ONCE_ENV_VAR] === "1"
+  if (parsedArgs.options.share) {
+    try {
+      const shareTunnel = await (deps.startShareTunnel ?? ((localUrl) => startShareTunnel(localUrl, {
+        log: (message) => deps.log(`${LOG_PREFIX} ${message}`),
+      })))(launchUrl)
+      shareTunnelStop = shareTunnel.stop
+      await logShareDetails(deps.log, shareTunnel.publicUrl, launchUrl, deps.renderShareQr ?? renderTerminalQr)
+    } catch (error) {
+      await stop()
+      deps.warn(`${LOG_PREFIX} failed to start Cloudflare share tunnel`)
+      if (error instanceof Error && error.message) {
+        deps.warn(`${LOG_PREFIX} ${error.message}`)
+      }
+      return { kind: "exited", code: 1 }
+    }
+  }
+
+  if (parsedArgs.options.openBrowser && !parsedArgs.options.share && !suppressOpenBrowser) {
+    deps.openUrl(launchUrl)
+  }
+
+  return {
+    kind: "started",
+    stop: async () => {
+      shareTunnelStop?.()
+      await stop()
+    },
+  }
+}
+
+export function openUrl(url: string) {
+  const platform = process.platform
+  if (platform === "darwin") {
+    spawnDetached("open", [url])
+  } else if (platform === "win32") {
+    spawnDetached("cmd", ["/c", "start", "", url])
+  } else {
+    spawnDetached("xdg-open", [url])
+  }
+  console.log(`${LOG_PREFIX} opened in default browser`)
+}
+
+export async function fetchLatestPackageVersion(packageName: string) {
+  const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`)
+  if (!response.ok) {
+    throw new Error(`registry returned ${response.status}`)
+  }
+
+  const payload = await response.json() as { version?: unknown }
+  if (typeof payload.version !== "string" || !payload.version.trim()) {
+    throw new Error("registry response did not include a version")
+  }
+
+  return payload.version
+}
+
+export function classifyInstallVersionFailure(output: string): UpdateInstallAttemptResult {
+  const normalizedOutput = output.trim()
+  if (/No version matching .* found|failed to resolve/i.test(normalizedOutput)) {
+    return {
+      ok: false,
+      errorCode: "version_not_live_yet",
+      userTitle: "Update not live yet",
+      userMessage: "This update is still propagating. Try again in a few minutes.",
+    }
+  }
+
+  return {
+    ok: false,
+    errorCode: "install_failed",
+    userTitle: "Update failed",
+    userMessage: `${APP_NAME} could not install the update. Try again later.`,
+  }
+}
+
+export function installPackageVersion(packageName: string, version: string) {
+  if (!hasCommand("bun")) {
+    return {
+      ok: false,
+      errorCode: "command_missing",
+      userTitle: "Bun not found",
+      userMessage: `${APP_NAME} could not find Bun to install the update.`,
+    } satisfies UpdateInstallAttemptResult
+  }
+
+  const result = spawnSync("bun", ["install", "-g", `${packageName}@${version}`], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  })
+  const stdout = result.stdout ?? ""
+  const stderr = result.stderr ?? ""
+  if (stdout) process.stdout.write(stdout)
+  if (stderr) process.stderr.write(stderr)
+  if (result.status === 0) {
+    return {
+      ok: true,
+      errorCode: null,
+      userTitle: null,
+      userMessage: null,
+    } satisfies UpdateInstallAttemptResult
+  }
+
+  return classifyInstallVersionFailure(`${stdout}\n${stderr}`)
+}

package/src/server/cli-supervisor.ts

@@ -0,0 +1,81 @@
+import process from "node:process"
+import { spawn } from "node:child_process"
+import { CLI_COMMAND, LOG_PREFIX } from "../shared/branding"
+import {
+  CLI_CHILD_ARGS_ENV_VAR,
+  CLI_CHILD_COMMAND_ENV_VAR,
+  CLI_CHILD_MODE,
+  CLI_CHILD_MODE_ENV_VAR,
+  CLI_SUPPRESS_OPEN_ONCE_ENV_VAR,
+  isUiUpdateRestart,
+  parseChildArgsEnv,
+  shouldRestartCliProcess,
+} from "./restart"
+
+interface ChildExit {
+  code: number | null
+  signal: NodeJS.Signals | null
+}
+
+function getChildProcessSpec() {
+  const command = process.env[CLI_CHILD_COMMAND_ENV_VAR] || CLI_COMMAND
+  const args = parseChildArgsEnv(process.env[CLI_CHILD_ARGS_ENV_VAR])
+  return { command, args }
+}
+
+function spawnChild(argv: string[]) {
+  const childProcess = getChildProcessSpec()
+  const suppressOpenThisChild = suppressOpenOnNextChild
+  suppressOpenOnNextChild = false
+  return new Promise<ChildExit>((resolve, reject) => {
+    const child = spawn(childProcess.command, [...childProcess.args, ...argv], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        [CLI_CHILD_MODE_ENV_VAR]: CLI_CHILD_MODE,
+        ...(suppressOpenThisChild ? { [CLI_SUPPRESS_OPEN_ONCE_ENV_VAR]: "1" } : {}),
+      },
+    })
+
+    const forwardSignal = (signal: NodeJS.Signals) => {
+      if (child.exitCode !== null) return
+      child.kill(signal)
+    }
+
+    const onSigint = () => {
+      forwardSignal("SIGINT")
+    }
+    const onSigterm = () => {
+      forwardSignal("SIGTERM")
+    }
+
+    process.on("SIGINT", onSigint)
+    process.on("SIGTERM", onSigterm)
+
+    child.once("error", (error) => {
+      process.off("SIGINT", onSigint)
+      process.off("SIGTERM", onSigterm)
+      reject(error)
+    })
+
+    child.once("exit", (code, signal) => {
+      process.off("SIGINT", onSigint)
+      process.off("SIGTERM", onSigterm)
+      resolve({ code, signal })
+    })
+  })
+}
+
+const argv = process.argv.slice(2)
+let suppressOpenOnNextChild = false
+
+while (true) {
+  const result = await spawnChild(argv)
+  if (shouldRestartCliProcess(result.code, result.signal)) {
+    suppressOpenOnNextChild = isUiUpdateRestart(result.code, result.signal)
+    console.log(`${LOG_PREFIX} supervisor restarting ${CLI_COMMAND} in the same terminal session`)
+    continue
+  }
+
+  process.exit(result.code ?? (result.signal ? 1 : 0))
+}

package/src/server/cli.ts

@@ -0,0 +1,78 @@
+import process from "node:process"
+import { LOG_PREFIX } from "../shared/branding"
+import { installConsoleTee } from "../shared/log-sink"
+
+// Observability (decision 0012): tee console output to VictoriaLogs when
+// VICTORIALOGS_URL is set; no-op otherwise. Installed first so all startup
+// logs are captured.
+installConsoleTee(process.env, "server")
+
+// Safety net: prevent stray unhandled rejections from crashing the server.
+// Root causes should still be fixed, but this prevents cascading process death
+// when a child process (e.g., Codex, vendored rg) dies unexpectedly.
+process.on("unhandledRejection", (reason) => {
+  const message = reason instanceof Error ? reason.message : String(reason)
+  console.warn(LOG_PREFIX, "unhandled rejection (swallowed):", message)
+})
+import {
+  fetchLatestPackageVersion,
+  installPackageVersion,
+  openUrl,
+  runCli,
+} from "./cli-runtime"
+import { CLI_STARTUP_UPDATE_RESTART_EXIT_CODE, CLI_UI_UPDATE_RESTART_EXIT_CODE } from "./restart"
+import { startServer } from "./server"
+
+// Read version from package.json at the package root
+const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json()
+const VERSION: string = pkg.version ?? "0.0.0"
+
+const argv = process.argv.slice(2)
+let resolveExitAction: ((action: "ui_restart" | "exit") => void) | null = null
+
+const result = await runCli(argv, {
+  version: VERSION,
+  bunVersion: Bun.version,
+  startServer: async (options) => {
+    const started = await startServer(options)
+    if (started.updateManager && options.update) {
+      started.updateManager.onChange((snapshot) => {
+        if (snapshot.status !== "restart_pending") return
+        console.log(`${LOG_PREFIX} update installed, shutting down current process for restart`)
+        resolveExitAction?.("ui_restart")
+      })
+    }
+
+    return started
+  },
+  fetchLatestVersion: fetchLatestPackageVersion,
+  installVersion: installPackageVersion,
+  openUrl,
+  log: console.log,
+  warn: console.warn,
+})
+
+if (result.kind === "exited") {
+  process.exit(result.code)
+}
+
+if (result.kind === "restarting") {
+  process.exit(result.reason === "startup_update" ? CLI_STARTUP_UPDATE_RESTART_EXIT_CODE : CLI_UI_UPDATE_RESTART_EXIT_CODE)
+}
+
+const exitAction = await new Promise<"ui_restart" | "exit">((resolve) => {
+  resolveExitAction = resolve
+
+  const shutdown = () => {
+    resolve("exit")
+  }
+
+  process.once("SIGINT", shutdown)
+  process.once("SIGTERM", shutdown)
+})
+
+await result.stop()
+if (exitAction === "ui_restart") {
+  console.log(`${LOG_PREFIX} current process stopped, handing restart back to supervisor`)
+}
+process.exit(exitAction === "ui_restart" ? CLI_UI_UPDATE_RESTART_EXIT_CODE : 0)

package/src/server/client-log-forwarder.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test"
+import { sanitizeClientLogs, buildNdjson, forwardClientLogs } from "./client-log-forwarder"
+
+describe("sanitizeClientLogs", () => {
+  test("keeps valid records and tags source/component", () => {
+    const out = sanitizeClientLogs({
+      logs: [{ level: "warn", msg: "hi", ts: "2026-05-27T10:00:00.000Z", url: "https://a/b" }],
+    })
+    expect(out).toEqual([
+      { _time: "2026-05-27T10:00:00.000Z", _msg: "hi", level: "warn", source: "frontend", component: "browser", url: "https://a/b" },
+    ])
+  })
+
+  test("drops entries with no message; defaults bad level to info; backfills bad ts", () => {
+    const now = new Date("2026-05-27T12:00:00.000Z")
+    const out = sanitizeClientLogs({ logs: [{ msg: "x", level: "nope", ts: "garbage" }, { level: "error" }] }, now)
+    expect(out).toHaveLength(1)
+    expect(out[0].level).toBe("info")
+    expect(out[0]._time).toBe("2026-05-27T12:00:00.000Z")
+  })
+
+  test("non-array / non-object bodies → empty", () => {
+    expect(sanitizeClientLogs(null)).toEqual([])
+    expect(sanitizeClientLogs({ logs: "x" })).toEqual([])
+    expect(sanitizeClientLogs({})).toEqual([])
+  })
+
+  test("caps record count and truncates long messages", () => {
+    const logs = Array.from({ length: 1500 }, () => ({ msg: "a".repeat(20000) }))
+    const out = sanitizeClientLogs({ logs })
+    expect(out.length).toBe(1000)
+    expect(out[0]._msg.length).toBe(8192)
+  })
+})
+
+describe("buildNdjson", () => {
+  test("newline-joins one JSON object per record", () => {
+    const recs = sanitizeClientLogs({ logs: [{ msg: "a" }, { msg: "b" }] })
+    const out = buildNdjson(recs)
+    expect(out.split("\n")).toHaveLength(2)
+    expect(JSON.parse(out.split("\n")[1])._msg).toBe("b")
+  })
+})
+
+describe("forwardClientLogs", () => {
+  test("ships ndjson to VL when VICTORIALOGS_URL set", async () => {
+    const calls: { url: string; body: string }[] = []
+    const fetchFn = (async (u: string, init?: RequestInit) => {
+      calls.push({ url: u, body: String(init?.body) }); return new Response(null, { status: 204 })
+    }) as unknown as typeof fetch
+    const n = await forwardClientLogs(
+      { logs: [{ msg: "one", level: "info" }] },
+      { VICTORIALOGS_URL: "http://127.0.0.1:9428" } as unknown as NodeJS.ProcessEnv,
+      fetchFn,
+    )
+    expect(n).toBe(1)
+    expect(calls[0].url).toBe("http://127.0.0.1:9428/insert/jsonline?_stream_fields=source,component")
+  })
+
+  test("no VL url → counts but does not ship", async () => {
+    let shipped = 0
+    const fetchFn = (async () => { shipped++; return new Response(null) }) as unknown as typeof fetch
+    const n = await forwardClientLogs({ logs: [{ msg: "x" }] }, {} as NodeJS.ProcessEnv, fetchFn)
+    expect(n).toBe(1)
+    expect(shipped).toBe(0)
+  })
+
+  test("fetch failure is swallowed", async () => {
+    const fetchFn = (async () => { throw new Error("down") }) as unknown as typeof fetch
+    await expect(
+      forwardClientLogs({ logs: [{ msg: "x" }] }, { VICTORIALOGS_URL: "http://x" } as unknown as NodeJS.ProcessEnv, fetchFn),
+    ).resolves.toBe(1)
+  })
+})

package/src/server/client-log-forwarder.ts

@@ -0,0 +1,75 @@
+/**
+ * Forward browser-shipped logs to VictoriaLogs (decision 0012).
+ *
+ * The frontend POSTs batches to `/api/logs`; this module sanitizes them
+ * (caps count + truncates message size, so a misbehaving/malicious client
+ * can't flood the store) and ships them to VictoriaLogs as `source=frontend`.
+ * VictoriaLogs stays localhost-only — the browser never reaches it directly.
+ *
+ * Fire-and-forget: VictoriaLogs being down or `VICTORIALOGS_URL` being unset
+ * must never make `/api/logs` fail (the client should never error on logging).
+ */
+
+const MAX_RECORDS = 1000
+const MAX_MSG_LEN = 8192
+const LEVELS = new Set(["debug", "info", "warn", "error"])
+
+export interface SanitizedClientLog {
+  _time: string
+  _msg: string
+  level: string
+  source: "frontend"
+  component: "browser"
+  url: string
+}
+
+/**
+ * Validate + clamp a raw `/api/logs` body into VL records. Pure.
+ * Drops malformed entries; never throws.
+ */
+export function sanitizeClientLogs(body: unknown, now: Date = new Date()): SanitizedClientLog[] {
+  const logs = (body as { logs?: unknown })?.logs
+  if (!Array.isArray(logs)) return []
+  const out: SanitizedClientLog[] = []
+  for (const raw of logs.slice(0, MAX_RECORDS)) {
+    if (typeof raw !== "object" || raw === null) continue
+    const r = raw as Record<string, unknown>
+    const msg = typeof r.msg === "string" ? r.msg.slice(0, MAX_MSG_LEN) : ""
+    if (!msg) continue
+    const level = typeof r.level === "string" && LEVELS.has(r.level) ? r.level : "info"
+    const ts = typeof r.ts === "string" && !Number.isNaN(Date.parse(r.ts)) ? r.ts : now.toISOString()
+    const recUrl = typeof r.url === "string" ? r.url.slice(0, 2048) : ""
+    out.push({ _time: ts, _msg: msg, level, source: "frontend", component: "browser", url: recUrl })
+  }
+  return out
+}
+
+/** Newline-delimited JSON for VL `/insert/jsonline`. Pure. */
+export function buildNdjson(records: SanitizedClientLog[]): string {
+  return records.map((r) => JSON.stringify(r)).join("\n")
+}
+
+/**
+ * Sanitize and ship a `/api/logs` body to VictoriaLogs. Returns the number of
+ * accepted records. Never throws; swallows network errors.
+ */
+export async function forwardClientLogs(
+  body: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+  fetchFn: typeof fetch = fetch,
+): Promise<number> {
+  const records = sanitizeClientLogs(body)
+  const url = env.VICTORIALOGS_URL?.trim()
+  if (records.length === 0 || !url) return records.length
+  const endpoint = `${url.replace(/\/$/, "")}/insert/jsonline?_stream_fields=source,component`
+  try {
+    await fetchFn(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-ndjson" },
+      body: buildNdjson(records),
+    })
+  } catch {
+    // observability must never break the ingest endpoint
+  }
+  return records.length
+}