opencode-ufr 0.2.0

package/src/daemon/window.ts

@@ -0,0 +1,126 @@
+export type Reservation = { verdict: "admit" | "queue" | "reject"; waitMs: number; at: number }
+
+/**
+ * Exact sliding-window admission control (port of the author's former
+ * self-hosted LiteLLM proxy's PoolLimiterCore).
+ *
+ * `times` is a sorted list of admission times. It may hold times in the future:
+ * reservations of queued requests. Keeping them in the same list is what keeps
+ * the window exact under load — a queued request already owns the slot it waits
+ * for. Not a token bucket: capacity + refill would allow up to 2× cap per window.
+ */
+export class SlidingWindow {
+  private times: number[] = []
+  readonly cap: number
+  readonly windowMs: number
+  readonly maxWaitMs: number
+  private readonly now: () => number
+  admitted = 0
+  queued = 0
+  rejected = 0
+
+  constructor(o: { cap: number; windowMs: number; maxWaitMs: number; now: () => number }) {
+    if (o.windowMs <= 0) throw new Error("windowMs must be > 0")
+    this.cap = Math.max(0, Math.floor(o.cap))
+    this.windowMs = o.windowMs
+    this.maxWaitMs = Math.max(0, o.maxWaitMs)
+    this.now = o.now
+  }
+
+  get enabled(): boolean {
+    return this.cap > 0
+  }
+
+  private prune(now: number): void {
+    const cutoff = now - this.windowMs
+    let i = 0
+    while (i < this.times.length && this.times[i]! <= cutoff) i++
+    if (i) this.times.splice(0, i)
+  }
+
+  private insert(t: number): void {
+    let i = this.times.length
+    while (i > 0 && this.times[i - 1]! > t) i--
+    this.times.splice(i, 0, t)
+  }
+
+  /** Admissions (including reservations) in the current window. */
+  inWindow(): number {
+    this.prune(this.now())
+    return this.times.length
+  }
+
+  headroom(): number {
+    return this.enabled ? Math.max(0, this.cap - this.inWindow()) : Number.POSITIVE_INFINITY
+  }
+
+  /** Milliseconds until a new request could be admitted; 0 = now. */
+  nextFreeInMs(): number {
+    if (!this.enabled) return 0
+    const now = this.now()
+    this.prune(now)
+    const n = this.times.length
+    if (n < this.cap) return 0
+    return Math.max(0, this.times[n - this.cap]! + this.windowMs - now)
+  }
+
+  reserve(): Reservation {
+    const now = this.now()
+    if (!this.enabled) return { verdict: "admit", waitMs: 0, at: now }
+    this.prune(now)
+    const n = this.times.length
+    if (n < this.cap) {
+      this.insert(now)
+      this.admitted++
+      return { verdict: "admit", waitMs: 0, at: now }
+    }
+    // The new request may enter the moment the cap-th most recent admission
+    // leaves the window: then cap-1 remain, plus this one = cap.
+    const at = this.times[n - this.cap]! + this.windowMs
+    const waitMs = Math.max(0, at - now)
+    if (waitMs <= this.maxWaitMs) {
+      this.insert(at)
+      this.queued++
+      return { verdict: "queue", waitMs, at }
+    }
+    this.rejected++
+    return { verdict: "reject", waitMs, at }
+  }
+
+  /** Book a slot at an explicit time (KeyPool uses it for keys in cooldown). */
+  reserveAt(t: number): void {
+    this.insert(t)
+    this.queued++
+  }
+
+  /** Give back a booked time, e.g. when the waiting client went away. */
+  release(t: number): boolean {
+    const i = this.times.indexOf(t)
+    if (i < 0) return false
+    this.times.splice(i, 1)
+    return true
+  }
+
+  /** Restore admissions after a restart. */
+  seed(times: number[]): void {
+    for (const t of times) this.insert(t)
+    this.prune(this.now())
+  }
+
+  oldest(): number | undefined {
+    this.prune(this.now())
+    return this.times[0]
+  }
+
+  snapshot() {
+    return {
+      enabled: this.enabled,
+      cap: this.cap,
+      windowMs: this.windowMs,
+      inWindow: this.inWindow(),
+      admitted: this.admitted,
+      queued: this.queued,
+      rejected: this.rejected,
+    }
+  }
+}

package/src/plugin/connect.ts

@@ -0,0 +1,113 @@
+/**
+ * The /connect integration: opencode's built-in provider-connect panel lists
+ * the "unifreiburg" integration; this plugin replaces its key method with one
+ * that shows the optional uni-login form (login + password) alongside the API
+ * key(s). When the user submits, opencode stores a Credential with the form
+ * answers; this module watches for it and applies it to the keyring + config,
+ * then restarts the gateway so the keys go live.
+ */
+
+import { applyConnect, splitKeys } from "../shared/connect"
+import type { Paths } from "../shared/paths"
+import { applyKeyChange } from "../cli/keys"
+
+export const UFR_INTEGRATION_ID = "unifreiburg"
+
+export type ConnectDeps = {
+  ctx: any // opencode plugin context (integration + storage domains)
+  paths: Paths
+  secrets: { get(alias: string): Promise<string | null>; set(alias: string, value: string): Promise<void>; delete(alias: string): Promise<boolean> }
+  log: (m: string) => void
+}
+
+type CredentialValue = { type?: string; key?: string; configuration?: Record<string, unknown> } | undefined
+
+/** Normalizes one opencode credential into a ConnectInput. */
+export function credentialToInput(cred: CredentialValue): { keys: string; login?: string; password?: string } | null {
+  if (!cred || cred.type && cred.type !== "key") return null
+  const cfg = (cred.configuration ?? {}) as Record<string, unknown>
+  const str = (v: unknown) => (typeof v === "string" ? v.trim() : "")
+  const keys = str(cred.key) || str(cfg.keys)
+  if (!keys) return null
+  return {
+    keys,
+    login: str(cfg.login) || undefined,
+    password: str(cfg.password) || undefined,
+  }
+}
+
+export type ConnectRegistration = { stop: () => void; applyNow: () => Promise<boolean> }
+
+export async function registerConnect(d: ConnectDeps): Promise<ConnectRegistration> {
+  const { ctx } = d
+  if (typeof ctx?.integration?.transform !== "function") {
+    d.log("this opencode version has no integration API — /connect stays as configured elsewhere")
+    return { stop: () => {}, applyNow: async () => false }
+  }
+
+  // Replace the key method of the unifreiburg integration with ours: the
+  // standard API-key(s) prompt plus the optional uni-login form.
+  await ctx.integration.transform((editor: any) => {
+    if (typeof editor?.method?.update !== "function") return
+    editor.method.update({
+      integrationID: UFR_INTEGRATION_ID,
+      method: {
+        type: "key",
+        label: "API keys (comma-separated) + optional uni login",
+        form: [
+          {
+            key: "login",
+            title: "Uni login (optional)",
+            type: "string",
+            placeholder: "fl240@uni-freiburg.de",
+            description: "Only needed off campus — the built-in VPN uses it. Leave empty on the uni network.",
+          },
+          {
+            key: "password",
+            title: "Uni password (optional)",
+            type: "string",
+            description: "Stored in the OS keyring, never on disk. Only with a login above.",
+          },
+        ],
+      },
+    })
+  })
+
+  // Apply a submitted credential once, then watch for changes.
+  let lastApplied = ""
+  const applyOnce = async (): Promise<boolean> => {
+    try {
+      const connection = await ctx.integration.connection.active(UFR_INTEGRATION_ID)
+      if (!connection) return false
+      const cred = (await ctx.integration.connection.resolve(connection)) as CredentialValue
+      const sig = JSON.stringify(cred?.configuration ?? {}) + "|" + (cred?.key ?? "")
+      if (sig === lastApplied) return false
+      lastApplied = sig
+      const input = credentialToInput(cred)
+      if (!input) {
+        d.log("/connect credential has no keys — nothing applied")
+        return false
+      }
+      const r = await applyConnect(input, { paths: d.paths, secrets: d.secrets, log: d.log })
+      if (r.errors.length > 0) {
+        for (const e of r.errors) d.log(`/connect: ${e}`)
+        return false
+      }
+      await applyKeyChange({ paths: d.paths, fetch: (u, i) => fetch(u, i), log: d.log })
+      return true
+    } catch (e) {
+      d.log(`/connect apply failed: ${(e as Error).message}`)
+      return false
+    }
+  }
+
+  await applyOnce()
+  const timer = setInterval(() => void applyOnce(), 60_000)
+  ;(timer as { unref?: () => void }).unref?.()
+  return {
+    stop: () => clearInterval(timer),
+    applyNow: applyOnce,
+  }
+}
+
+export { splitKeys }

package/src/plugin/ensure-daemon.ts

@@ -0,0 +1,101 @@
+import { spawn } from "node:child_process"
+import { mkdirSync } from "node:fs"
+import { readJson, readText } from "../shared/fs"
+import type { Paths } from "../shared/paths"
+
+export type DaemonInfo = { port: number; pid: number; version: string }
+export type Conn = { port: number; token: string }
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>
+
+export function isNewer(a: string, b: string): boolean {
+  const pa = a.split(".").map(Number)
+  const pb = b.split(".").map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (x !== y) return x > y
+  }
+  return false
+}
+
+export async function readDaemonInfo(paths: Paths): Promise<DaemonInfo | null> {
+  const j = (await readJson(paths.daemonFile)) as Partial<DaemonInfo> | null
+  return j && typeof j.port === "number" && typeof j.version === "string" ? { port: j.port, pid: j.pid ?? 0, version: j.version } : null
+}
+
+async function readToken(paths: Paths): Promise<string | null> {
+  return (await readText(paths.tokenFile))?.trim() || null
+}
+
+/** Find the shared daemon, replace it if we are newer and it is idle, or start one. */
+export async function ensureDaemon(o: {
+  paths: Paths
+  version: string
+  spawn: () => void
+  fetch?: FetchLike
+  sleep?: (ms: number) => Promise<void>
+  timeoutMs?: number
+  now?: () => number
+}): Promise<Conn> {
+  const f: FetchLike = o.fetch ?? ((u, i) => fetch(u, i))
+  const sleep = o.sleep ?? ((ms: number) => Bun.sleep(ms))
+  const now = o.now ?? Date.now
+  const health = async (port: number) => {
+    try {
+      const r = await f(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2_000) })
+      return r.ok ? ((await r.json()) as { version?: string }) : null
+    } catch {
+      return null
+    }
+  }
+  const authed = (token: string, method = "GET"): RequestInit => ({
+    method,
+    headers: { Authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(2_000),
+  })
+
+  const info = await readDaemonInfo(o.paths)
+  if (info) {
+    const h = await health(info.port)
+    const token = await readToken(o.paths)
+    if (h && token) {
+      if (!h.version || !isNewer(o.version, h.version)) return { port: info.port, token }
+      const st = (await f(`http://127.0.0.1:${info.port}/v1/_status`, authed(token))
+        .then((r) => (r.ok ? r.json() : null))
+        .catch(() => null)) as { inFlight?: number } | null
+      if (!st || (st.inFlight ?? 0) > 0) return { port: info.port, token } // upgrade later, never mid-request
+      await f(`http://127.0.0.1:${info.port}/v1/_shutdown`, authed(token, "POST")).catch(() => null)
+      for (let i = 0; i < 25 && (await health(info.port)); i++) await sleep(200)
+    }
+  }
+
+  o.spawn()
+  // Startup can take up to ~35 s: two catalog fetches (models.json, UFR /api/models)
+  // with 15 s and 20 s timeouts before /health answers.
+  const timeoutMs = o.timeoutMs ?? 40_000
+  const deadline = now() + timeoutMs
+  while (now() < deadline) {
+    await sleep(200)
+    const next = await readDaemonInfo(o.paths)
+    const token = await readToken(o.paths)
+    if (next && token && (await health(next.port))) return { port: next.port, token }
+  }
+  throw new Error(`the opencode-ufr gateway did not start within ${Math.round(timeoutMs / 1000)} s — see daemon.log`)
+}
+
+/**
+ * Start the daemon detached on the runtime that runs opencode (BUN_BE_BUN: opencode's own Bun).
+ * It runs in `cwd` (the state directory), never in the spawning project: Bun auto-loads
+ * .env / bunfig.toml from the working directory, and on Windows the folder would stay locked.
+ */
+export function spawnDaemon(entry: string, cwd: string): void {
+  mkdirSync(cwd, { recursive: true })
+  const child = spawn(process.execPath, [entry], {
+    cwd,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: { ...process.env, BUN_BE_BUN: "1" },
+  })
+  child.unref()
+}

package/src/plugin/index.ts

@@ -0,0 +1,93 @@
+import { fileURLToPath } from "node:url"
+import type { OpencodeStamp } from "../daemon/catalog"
+import { type Paths, resolvePaths } from "../shared/paths"
+import { KeyringStore } from "../shared/secrets"
+import { VERSION } from "../shared/version"
+import { type Conn, ensureDaemon, spawnDaemon } from "./ensure-daemon"
+import { registerConnect } from "./connect"
+import { toModelInfo } from "./model-info"
+
+const DAEMON_ENTRY = fileURLToPath(new URL("../daemon/main.ts", import.meta.url))
+
+function log(msg: string): void {
+  console.warn(`[opencode-ufr] ${msg}`)
+}
+
+async function connect(paths: Paths): Promise<Conn> {
+  return ensureDaemon({ paths, version: VERSION, spawn: () => spawnDaemon(DAEMON_ENTRY, paths.stateDir) })
+}
+
+async function heartbeat(conn: Conn, paths: Paths): Promise<void> {
+  const ok = await fetch(`http://127.0.0.1:${conn.port}/v1/_client/heartbeat`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${conn.token}` },
+    signal: AbortSignal.timeout(5_000),
+  })
+    .then((r) => r.ok)
+    .catch(() => false)
+  // Port and token are stable, so a restarted daemon serves the provider we already registered.
+  if (!ok) await connect(paths).catch((e) => log(`gateway restart failed: ${(e as Error).message}`))
+}
+
+export default {
+  id: "opencode-ufr",
+  async setup(ctx: any) {
+    const options = (ctx?.options ?? {}) as Record<string, unknown>
+    const providerId = typeof options.providerId === "string" ? options.providerId : "unifreiburg"
+    const providerName = typeof options.providerName === "string" ? options.providerName : "Uni Freiburg"
+    const paths = resolvePaths()
+
+    let conn: Conn
+    try {
+      conn = await connect(paths)
+    } catch (e) {
+      log(`${(e as Error).message} — run \`ufr status\``)
+      return
+    }
+    const list = await fetch(`http://127.0.0.1:${conn.port}/v1/models`, {
+      headers: { Authorization: `Bearer ${conn.token}` },
+      signal: AbortSignal.timeout(10_000),
+    })
+      .then(async (r) => (r.ok ? ((await r.json()) as { data: { id: string; opencode: OpencodeStamp }[] }).data : []))
+      .catch(() => [])
+    if (list.length === 0) {
+      // Never register an empty provider: it breaks the whole model picker.
+      log("no models available — run `ufr setup`, connect to the uni VPN, then `ufr status` for details")
+      return
+    }
+    if (typeof ctx?.provider?.transform !== "function") {
+      log("this opencode version has no ctx.provider.transform — cannot register the provider")
+      return
+    }
+    const models = list.map((m) => toModelInfo(providerId, m.id, m.opencode))
+    await ctx.provider.transform((editor: any) => {
+      editor.add({
+        info: {
+          id: providerId,
+          name: providerName,
+          activation: "enabled",
+          package: "@opencode/ai/providers/openai-compatible",
+          settings: { baseURL: `http://127.0.0.1:${conn.port}/v1`, apiKey: conn.token },
+        },
+        models,
+      })
+    })
+    log(`registered ${providerId} with ${models.length} models`)
+    // /connect integration: uni login (optional) form on the unifreiburg entry
+    const stopConnect = await registerConnect({
+      ctx,
+      paths,
+      secrets: new KeyringStore(),
+      log,
+    }).catch((e) => {
+      log(`/connect integration failed: ${(e as Error).message}`)
+      return { stop: () => {}, applyNow: async () => false }
+    })
+    const beat = setInterval(() => void heartbeat(conn, paths), 60_000)
+    ;(beat as { unref?: () => void }).unref?.()
+    return () => {
+      clearInterval(beat)
+      stopConnect.stop()
+    }
+  },
+}

package/src/plugin/model-info.ts

@@ -0,0 +1,35 @@
+import type { OpencodeStamp } from "../daemon/catalog"
+
+/** Map a daemon stamp onto opencode's V2 Model.Info shape (as of opencode 2.0.18). */
+export function toModelInfo(providerID: string, id: string, s: Omit<OpencodeStamp, "cost"> & { cost?: OpencodeStamp["cost"] }) {
+  return {
+    id,
+    modelID: id,
+    providerID,
+    name: s.name,
+    capabilities: {
+      tools: s.tool_call,
+      input: s.attachment ? ["text", "image"] : ["text"],
+      output: ["text"],
+    },
+    limit: { context: s.limit.context, output: s.limit.output },
+    // Required: Model.snapshot() sorts the whole registry on time.released, so a
+    // model without it crashes model resolution for *every* provider. UFR has no
+    // release dates; 0 means unknown and keeps the sort deterministic.
+    time: { released: 0 },
+    // Required as an array even when empty: one entry without variants makes the
+    // server reject the whole /model list, and the picker shows nothing.
+    variants: [],
+    status: "active",
+    enabled: true,
+    // Always an array with every nested object present: opencode dereferences
+    // cost[].cache.read unguarded when it tallies a step, after the model replied.
+    cost: [
+      {
+        input: s.cost?.input ?? 0,
+        output: s.cost?.output ?? 0,
+        cache: { read: s.cost?.cache_read ?? 0, write: s.cost?.cache_write ?? 0 },
+      },
+    ],
+  }
+}

package/src/shared/config.ts

@@ -0,0 +1,170 @@
+import { readText, writeFileAtomic } from "./fs"
+
+export type Config = {
+  schema: 1
+  port: number | null
+  transport: { type: "direct" | "auto" }
+  vpn: { gateway: string; mode: "auto" | "always" }
+  upstream: { baseUrl: string; requestTimeoutS: number }
+  keys: string[]
+  limits: {
+    keyRpm: number
+    keyWindowS: number
+    keyMaxWaitS: number
+    poolPerHour: number
+    poolWindowS: number
+    poolMaxWaitS: number
+    maxUpstreamAttempts: number
+  }
+  breaker: { tripThreshold: number; ladderS: number[]; probeTimeoutS: number }
+  allowPaid: boolean
+  dailyBudgetUsd: number
+  catalog: { url: string; refreshHours: number }
+  idleShutdownMin: number
+}
+
+export const DEFAULTS: Config = {
+  schema: 1,
+  port: null,
+  // "auto": reach UFR directly when possible, otherwise through the built-in
+  // Fortinet tunnel (needs a stored uni login; behaves like "direct" otherwise).
+  transport: { type: "auto" },
+  vpn: { gateway: "https://fortivpn.uni-freiburg.de", mode: "auto" },
+  upstream: { baseUrl: "https://openwebui.uni-freiburg.de/api", requestTimeoutS: 600 },
+  keys: [],
+  limits: {
+    keyRpm: 18,
+    keyWindowS: 60,
+    keyMaxWaitS: 60,
+    poolPerHour: 800,
+    poolWindowS: 3600,
+    poolMaxWaitS: 20,
+    maxUpstreamAttempts: 4,
+  },
+  breaker: { tripThreshold: 3, ladderS: [30, 120, 300, 900, 1800, 3600], probeTimeoutS: 120 },
+  allowPaid: false,
+  dailyBudgetUsd: 20,
+  catalog: { url: "https://raw.githubusercontent.com/FinleyLaempe/opencode-ufr/main/models.json", refreshHours: 6 },
+  idleShutdownMin: 5,
+}
+
+export class ConfigError extends Error {}
+
+type Rule = "int>=0" | "int>=1" | "num>=0" | "bool" | "str" | "port|null" | "aliases" | "int>=1[]" | "transport" | "vpnMode"
+
+const RULES: Record<string, Rule> = {
+  port: "port|null",
+  "transport.type": "transport",
+  "vpn.gateway": "str",
+  "vpn.mode": "vpnMode",
+  "upstream.baseUrl": "str",
+  "upstream.requestTimeoutS": "int>=1",
+  keys: "aliases",
+  "limits.keyRpm": "int>=1",
+  "limits.keyWindowS": "int>=1",
+  "limits.keyMaxWaitS": "int>=0",
+  "limits.poolPerHour": "int>=0",
+  "limits.poolWindowS": "int>=1",
+  "limits.poolMaxWaitS": "int>=0",
+  "limits.maxUpstreamAttempts": "int>=1",
+  "breaker.tripThreshold": "int>=1",
+  "breaker.ladderS": "int>=1[]",
+  "breaker.probeTimeoutS": "int>=1",
+  allowPaid: "bool",
+  dailyBudgetUsd: "num>=0",
+  "catalog.url": "str",
+  "catalog.refreshHours": "int>=1",
+  idleShutdownMin: "int>=1",
+}
+
+// Upper bounds for values that become setTimeout/setInterval delays: above 2^31-1 ms
+// Bun clamps a timer to 1 ms, which would turn e.g. the catalog refresh into a tight loop.
+// For an array (breaker.ladderS) the bound applies to every entry.
+const MAX: Record<string, number> = {
+  "upstream.requestTimeoutS": 86_400,
+  "limits.keyWindowS": 86_400,
+  "limits.keyMaxWaitS": 86_400,
+  "limits.poolWindowS": 86_400,
+  "limits.poolMaxWaitS": 86_400,
+  "breaker.ladderS": 86_400,
+  "breaker.probeTimeoutS": 86_400,
+  "catalog.refreshHours": 168,
+  idleShutdownMin: 1_440,
+}
+
+export const ALIAS_RE = /^[A-Za-z0-9._-]{1,32}$/
+
+const isObj = (x: unknown): x is Record<string, unknown> => typeof x === "object" && x !== null && !Array.isArray(x)
+const isInt = (x: unknown): x is number => typeof x === "number" && Number.isInteger(x)
+
+function deepMerge(base: unknown, over: unknown): unknown {
+  if (!isObj(base) || !isObj(over)) return over === undefined ? base : over
+  const out: Record<string, unknown> = { ...base }
+  for (const [k, v] of Object.entries(over)) out[k] = deepMerge(base[k], v)
+  return out
+}
+
+function get(obj: unknown, path: string): unknown {
+  return path.split(".").reduce<unknown>((o, k) => (isObj(o) ? o[k] : undefined), obj)
+}
+
+function valid(v: unknown, rule: Rule): boolean {
+  switch (rule) {
+    case "int>=0":
+      return isInt(v) && v >= 0
+    case "int>=1":
+      return isInt(v) && v >= 1
+    case "num>=0":
+      return typeof v === "number" && Number.isFinite(v) && v >= 0
+    case "bool":
+      return typeof v === "boolean"
+    case "str":
+      return typeof v === "string" && v.length > 0
+    case "port|null":
+      return v === null || (isInt(v) && v >= 1 && v <= 65535)
+    case "aliases":
+      return Array.isArray(v) && v.every((s) => typeof s === "string" && ALIAS_RE.test(s))
+    case "int>=1[]":
+      return Array.isArray(v) && v.length > 0 && v.every((x) => isInt(x) && x >= 1)
+    case "transport":
+      return v === "direct" || v === "auto"
+    case "vpnMode":
+      return v === "auto" || v === "always"
+  }
+}
+
+export function mergeConfig(raw: unknown): Config {
+  if (raw !== undefined && !isObj(raw)) throw new ConfigError("config: the top level must be a JSON object")
+  if (isObj(raw) && raw.schema !== undefined && raw.schema !== 1) {
+    throw new ConfigError(`config: unsupported schema ${JSON.stringify(raw.schema)} (this version reads schema 1)`)
+  }
+  const cfg = deepMerge(structuredClone(DEFAULTS), raw ?? {}) as Config
+  for (const [path, rule] of Object.entries(RULES)) {
+    const v = get(cfg, path)
+    if (!valid(v, rule)) throw new ConfigError(`config: ${path} is invalid (${JSON.stringify(v)}), expected ${rule}`)
+    const max = MAX[path]
+    if (max !== undefined && (Array.isArray(v) ? v : [v]).some((x) => (x as number) > max)) {
+      const what = Array.isArray(v) ? "every entry must be" : "must be"
+      throw new ConfigError(`config: ${path} is too large (${JSON.stringify(v)}), ${what} at most ${max}`)
+    }
+  }
+  if (new Set(cfg.keys).size !== cfg.keys.length) throw new ConfigError("config: keys contains duplicate aliases")
+  return { ...cfg, schema: 1 }
+}
+
+export async function loadConfig(file: string): Promise<Config> {
+  const text = await readText(file)
+  if (text === null) return structuredClone(DEFAULTS)
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch (e) {
+    throw new ConfigError(`config: ${file} is not valid JSON (${(e as Error).message})`)
+  }
+  return mergeConfig(raw)
+}
+
+export async function saveConfig(file: string, cfg: Config): Promise<void> {
+  mergeConfig(cfg) // refuse to write something we could not read back
+  await writeFileAtomic(file, JSON.stringify(cfg, null, 2) + "\n")
+}