@better-forge/config-as-code 0.0.0-stage → 0.1.0

package/src/document.ts

@@ -0,0 +1,199 @@
+export type Json = Record<string, unknown>
+export const isObject = (value: unknown): value is Json => !!value && typeof value === 'object' && !Array.isArray(value)
+
+export interface ConfigProblem { path: string; message: string }
+
+/** The file is not valid; `problems` lists what is wrong with it, not just the first thing. */
+export class ConfigInvalidError extends Error {
+  constructor(readonly problems: ConfigProblem[]) {
+    super(problems[0] ? `${problems[0].path}: ${problems[0].message}` : 'Invalid configuration')
+  }
+}
+
+/** Most problems a file reports: the first ones are the ones to fix first. */
+const MAX_PROBLEMS = 100
+
+/** Collects what is wrong with a file. */
+export class Problems {
+  readonly list: ConfigProblem[] = []
+  add = (path: string, message: string) => { if (this.list.length < MAX_PROBLEMS) this.list.push({ path, message }) }
+  get any() { return this.list.length > 0 }
+}
+
+/** Shortens text that comes from a request before it is repeated in an answer, so an error cannot be made to echo a megabyte. */
+export function clip(value: string, max = 80): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value
+}
+
+/** Whether `value` nests objects or lists deeper than `max` levels. Checked without recursion, so it cannot overflow the stack. */
+export function nestedDeeperThan(value: unknown, max: number): boolean {
+  const pending: Array<[unknown, number]> = [[value, 0]]
+  while (pending.length) {
+    const [current, depth] = pending.pop()!
+    if (!current || typeof current !== 'object') continue
+    if (depth >= max) return true
+    for (const inner of Object.values(current)) pending.push([inner, depth + 1])
+  }
+  return false
+}
+
+/** The same value written with its keys in a fixed order, so equal settings compare equal whatever their order. */
+export function canonical(value: unknown): string {
+  return JSON.stringify(value, (_key, inner) => isObject(inner) ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]])) : inner)
+}
+
+/** Orders documents by key. A tie sorts the second one first, which never happens: keys are unique. */
+export const byKey = (a: { key: string }, b: { key: string }) => (a.key < b.key ? -1 : 1)
+
+/** Reports every field of `entry` that is not in `allowed`. */
+export function unknownFields(entry: Json, allowed: readonly string[], path: string, problems: Problems): void {
+  for (const field of Object.keys(entry)) if (!allowed.includes(field)) problems.add(`${path}.${clip(field)}`, 'is not a known setting')
+}
+
+/** Where a name the parser would treat specially (`__proto__`) appears in a document, or null. Walks without recursion. */
+export function forbiddenNameAt(document: unknown, label: string): string | null {
+  const pending: Array<[unknown, string]> = [[document, label]]
+  while (pending.length) {
+    const [value, path] = pending.pop()!
+    if (!value || typeof value !== 'object') continue
+    if (!Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, '__proto__')) return `${path}.__proto__`
+    const entries: Array<[string, unknown]> = Array.isArray(value) ? value.map((item, index) => [`[${index}]`, item]) : Object.entries(value)
+    for (const [name, inner] of entries) pending.push([inner, name.startsWith('[') ? `${path}${name}` : `${path}.${clip(name)}`])
+  }
+  return null
+}
+
+/** A dependency cycle among `edges` (key -> keys it depends on), as `a → b → a`, or null. */
+export function findCycle(edges: Map<string, string[]>): string | null {
+  const done = new Set<string>()
+  const stack: string[] = []
+  const visit = (key: string): string | null => {
+    const at = stack.indexOf(key)
+    if (at >= 0) return [...stack.slice(at), key].join(' → ')
+    if (done.has(key)) return null
+    stack.push(key)
+    for (const next of edges.get(key) ?? []) {
+      const cycle = visit(next)
+      if (cycle) return cycle
+    }
+    stack.pop()
+    done.add(key)
+    return null
+  }
+  for (const key of edges.keys()) {
+    const cycle = visit(key)
+    if (cycle) return cycle
+  }
+  return null
+}
+
+// ── References to vault secrets ──────────────────────────────────────────────
+
+/** The vaults and secrets of an installation, as far as a file needs to name them. */
+export interface VaultRows {
+  vaults: ReadonlyArray<{ id: number; name: string }>
+  secrets: ReadonlyArray<{ id: number; vaultId: number; name: string }>
+}
+
+/** A vault secret named instead of numbered, so the file means the same on another installation. */
+export interface ConfigVaultRef { vault: string; secret: string; fieldMapping?: Record<string, string> }
+
+/** `{ vault: 'Production', secret: 'db-login' }` back to the ids this installation knows them by. */
+export function createVaultResolver(rows: VaultRows) {
+  const vaultsByName = new Map<string, number[]>()
+  for (const vault of rows.vaults) vaultsByName.set(vault.name, [...(vaultsByName.get(vault.name) ?? []), vault.id])
+  const secretId = new Map(rows.secrets.map((secret) => [`${secret.vaultId}:${secret.name}`, secret.id]))
+
+  return function resolve(value: unknown, path: string, problems: Problems): unknown {
+    if (Array.isArray(value)) return value.map((item, index) => resolve(item, `${path}[${index}]`, problems))
+    if (!isObject(value)) return value
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => {
+      if (key !== 'vault') return [key, resolve(inner, `${path}.${key}`, problems)]
+      const at = `${path}.vault`
+      if (!isObject(inner) || typeof inner['vault'] !== 'string' || typeof inner['secret'] !== 'string') {
+        problems.add(at, 'must name the vault and the secret: { vault: <name>, secret: <name> }')
+        return [key, inner]
+      }
+      if ('vaultId' in inner || 'secretId' in inner) problems.add(at, 'a configuration file names a vault secret, it does not use numeric ids')
+      const found = vaultsByName.get(inner['vault']) ?? []
+      if (found.length !== 1) {
+        problems.add(at, found.length === 0
+          ? (inner['vault'].startsWith('(deleted') ? `${clip(inner['vault'])} refers to a vault that no longer exists` : `unknown vault "${clip(inner['vault'])}"`)
+          : `more than one vault is named "${clip(inner['vault'])}"; rename one of them`)
+        return [key, inner]
+      }
+      const secret = secretId.get(`${found[0]}:${inner['secret']}`)
+      if (secret === undefined) {
+        problems.add(at, inner['secret'].startsWith('(deleted') ? `${clip(inner['secret'])} refers to a secret that no longer exists` : `vault "${clip(inner['vault'])}" has no secret "${clip(inner['secret'])}"`)
+        return [key, inner]
+      }
+      return [key, { vaultId: found[0], secretId: secret, ...(isObject(inner['fieldMapping']) ? { fieldMapping: inner['fieldMapping'] } : {}) }]
+    }))
+  }
+}
+
+/** The file would refer to something it cannot name unambiguously, so it could not be read back. */
+export class ConfigExportError extends Error {}
+
+const deleted = (what: string, id: unknown) => `(deleted ${what} ${String(id)})`
+
+function isVaultRef(value: unknown): value is { vaultId: number; secretId: number; fieldMapping?: unknown } {
+  return isObject(value) && typeof value['vaultId'] === 'number' && typeof value['secretId'] === 'number'
+}
+
+/** Replaces every `vault: { vaultId, secretId }` reference in a config with the names of the vault and secret. */
+export function createVaultExporter(rows: VaultRows) {
+  const nameCount = new Map<string, number>()
+  for (const vault of rows.vaults) nameCount.set(vault.name, (nameCount.get(vault.name) ?? 0) + 1)
+  const vaultName = new Map(rows.vaults.map((vault) => [vault.id, vault.name]))
+  const secret = new Map(rows.secrets.map((row) => [row.id, row]))
+
+  function exportRef(ref: { vaultId: number; secretId: number; fieldMapping?: unknown }): ConfigVaultRef {
+    const vault = vaultName.get(ref.vaultId)
+    const found = secret.get(ref.secretId)
+    if (vault !== undefined && (nameCount.get(vault) ?? 0) > 1) {
+      throw new ConfigExportError(`More than one vault is named "${vault}", so a reference to it cannot be exported. Rename one of them.`)
+    }
+    return {
+      vault: vault ?? deleted('vault', ref.vaultId),
+      secret: found && found.vaultId === ref.vaultId ? found.name : deleted('secret', ref.secretId),
+      ...(isObject(ref.fieldMapping) ? { fieldMapping: ref.fieldMapping as Record<string, string> } : {}),
+    }
+  }
+
+  return function exportRefs(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map((item) => exportRefs(item))
+    if (!isObject(value)) return value
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) =>
+      [key, key === 'vault' && isVaultRef(inner) ? exportRef(inner) : exportRefs(inner)]))
+  }
+}
+
+// ── Fields every kind of document reads the same way ─────────────────────────
+
+/** A list of keys (`items: [a, b]`), without repeats; problems are reported at `path`. */
+export function keyList(value: unknown, path: string, problems: Problems, isValidKey: (key: unknown) => boolean): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+    problems.add(path, 'must be a list of keys')
+    return []
+  }
+  for (const key of value) if (!isValidKey(key)) problems.add(path, `"${clip(key)}" is not a valid key`)
+  return [...new Set(value as string[])]
+}
+
+/** The key of a document, or '' (with a problem) when it has none that is usable; a repeat within `seen` is a problem too. */
+export function documentKey(
+  entry: Json, path: string, seen: Set<string>, problems: Problems,
+  keys: { isValid: (key: unknown) => boolean; error: string },
+): string {
+  const key = entry['key']
+  if (!keys.isValid(key)) {
+    problems.add(`${path}.key`, key === undefined ? 'is required' : keys.error)
+    return ''
+  }
+  const text = key as string
+  if (seen.has(text)) problems.add(`${path}.key`, `"${clip(text)}" is used by another document`)
+  seen.add(text)
+  return text
+}

package/src/engine.ts

@@ -0,0 +1,258 @@
+import { clip, ConfigInvalidError, createVaultExporter, createVaultResolver, forbiddenNameAt, isObject, Problems, type Json, type VaultRows } from './document.js'
+
+export type ChangeAction = 'create' | 'update' | 'delete' | 'unchanged'
+
+export interface ConfigChange {
+  kind: string
+  /** The key of the object the document describes. */
+  key?: string
+  action: ChangeAction
+  /** For an update: which settings differ. Never their values, which may be secrets. */
+  fields?: string[]
+}
+
+export interface ImportResult {
+  dryRun: boolean
+  /** `delete` is present only for an import with `prune`. */
+  summary: Record<'create' | 'update' | 'unchanged', number> & { delete?: number }
+  changes: ConfigChange[]
+}
+
+/** What one change did, for the audit log. */
+export interface AuditEntry { action: 'create' | 'update' | 'delete'; entity: string; id: number | string; name: string; diff: Json }
+
+export interface ImportOptions<Actor> {
+  dryRun: boolean
+  actor: Actor
+  /** Set when the request is made with an API token: what it may do is decided per kind. */
+  token?: { scopes: readonly string[] } | undefined
+  /** Also delete the objects of the kinds the documents hold that the documents do not mention. Off by default. */
+  prune?: boolean
+}
+
+/** What a kind sees while it reads the documents of a file. */
+export interface PlanContext<State> {
+  state: State
+  token: { scopes: readonly string[] } | undefined
+  problems: Problems
+  /** `{ vault: <name>, secret: <name> }` references in a config, turned into the ids of this installation. */
+  resolveVaults: (value: unknown, path: string) => unknown
+  /** The documents of a kind the file holds, as that kind parsed them. */
+  desired: (kind: string) => unknown[]
+  /** The keys of a kind that an import with `prune` deletes: they do not exist afterwards, so nothing may link to them. */
+  removed: (kind: string) => ReadonlySet<string>
+}
+
+/** What a kind sees while it writes. */
+export interface ApplyContext<State> {
+  state: State
+  now: number
+  /** Ids by key, per kind: the objects that exist now, plus those created so far in this run. */
+  ids: (kind: string) => Map<string, number>
+}
+
+/**
+ * One kind of document. `parse` reads a document of the kind (reporting problems), `plan` compares what the file
+ * holds with the installation and says what would change, `apply` writes it, `link` runs after every kind is written
+ * (for references to objects that might be created later in the same file), `export` writes the kind out.
+ */
+export interface ConfigKind<State, ExportState, Desired = any, Planned = any> { // eslint-disable-line @typescript-eslint/no-explicit-any
+  kind: string
+  parse: (entry: Json, index: number, seen: Set<string>, problems: Problems) => Desired | null
+  plan: (desired: Desired[], ctx: PlanContext<State>) => { planned: Planned; changes: ConfigChange[] }
+  /** The ids of the objects of this kind that exist, by key. */
+  existingIds: (state: State) => Map<string, number>
+  apply: (planned: Planned, ctx: ApplyContext<State>) => Promise<AuditEntry[]>
+  link?: (planned: Planned, ctx: ApplyContext<State>) => Promise<void>
+  /** Deletes the objects with these keys, and whatever links to them. A kind without it is never pruned. */
+  remove?: (keys: string[], ctx: ApplyContext<State>) => Promise<AuditEntry[]>
+  /** The documents of this kind, sorted by key. `only` limits them to one key (and nothing else is written out). */
+  export: (state: ExportState, ctx: ExportContext) => Json[]
+}
+
+export interface ExportContext {
+  /** Replaces the vault references of a config with the names of the vault and secret. */
+  exportVaultRefs: (value: unknown) => unknown
+  /** The rows to write out: all of them, or only the one asked for. */
+  wanted: <T extends { key: string }>(rows: T[], kind: string) => T[]
+  /** Whether the kind is part of this export (a kind may be left out for a reader who may not see it). */
+  included: (kind: string) => boolean
+}
+
+export interface ConfigEngineOptions<State, ExportState, Actor> {
+  /** The kinds, in the order messages name them. */
+  kinds: ReadonlyArray<ConfigKind<State, ExportState>>
+  /** The order kinds are planned, written and exported in (kind names); defaults to `kinds`. */
+  order?: readonly string[]
+  /** Reads what the installation holds. Called inside the transaction when the file is applied. */
+  loadState: () => Promise<State>
+  /** Reads what an export needs; a kind not in `included` need not be read. */
+  loadExportState: (included: ReadonlySet<string>) => Promise<ExportState>
+  vaultRows: (state: State) => VaultRows
+  exportVaultRows: (state: ExportState) => VaultRows
+  /** Runs `work` so that everything it writes happens, or none of it does. */
+  transaction: <T>(work: () => Promise<T>) => Promise<T>
+  audit: { write: (actor: Actor, action: 'create' | 'update' | 'delete', entity: string, id: number | string | null, name: string, diff?: Json) => Promise<void> }
+  /** Runs once after a successful apply that changed something, before the audit entries are written. */
+  afterApply?: () => Promise<void>
+  /** Entity type of the summary entry written to the audit log. */
+  auditEntity?: string
+}
+
+/** Makes the installation match the documents, completely or not at all, and writes it out again as documents. */
+export function createConfigEngine<State, ExportState, Actor>(options: ConfigEngineOptions<State, ExportState, Actor>) {
+  const kinds = new Map(options.kinds.map((kind) => [kind.kind, kind]))
+  const names = options.kinds.map((kind) => kind.kind)
+  const order = (options.order ?? names).map((name) => kinds.get(name)!)
+
+  /** The kinds a list of documents contains, so that the caller can check it may import each. Documents of no known kind are ignored here. */
+  function kindsIn(documents: unknown[]): Set<string> {
+    const found = new Set<string>()
+    for (const document of documents) {
+      if (isObject(document) && names.includes(document['kind'] as string)) found.add(document['kind'] as string)
+    }
+    return found
+  }
+
+  function parseDocuments(documents: unknown[], problems: Problems): Map<string, unknown[]> {
+    const desired = new Map<string, unknown[]>(names.map((name) => [name, []]))
+    const seenKeys = new Map<string, Set<string>>(names.map((name) => [name, new Set()]))
+
+    documents.forEach((document, index) => {
+      const label = `document ${index + 1}`
+      const poisoned = forbiddenNameAt(document, label)
+      if (poisoned) { problems.add(poisoned, '"__proto__" is not allowed as a name'); return }
+      if (!isObject(document)) { problems.add(label, 'must be an object with a kind'); return }
+
+      const kind = kinds.get(document['kind'] as string)
+      if (!kind) {
+        problems.add(`${label}.kind`, document['kind'] === undefined
+          ? `is required: one of ${names.join(', ')}`
+          : `"${clip(String(document['kind']))}" is not a kind; use one of ${names.join(', ')}`)
+        return
+      }
+      const parsed = kind.parse(document, index, seenKeys.get(kind.kind)!, problems)
+      if (parsed) desired.get(kind.kind)!.push(parsed)
+    })
+    return desired
+  }
+
+  /** The keys to delete, per kind. A kind with no document in the file is left alone, so an empty file prunes nothing. */
+  function stale(state: State, desired: Map<string, unknown[]>): Map<string, string[]> {
+    const found = new Map<string, string[]>()
+    for (const kind of order) {
+      const documents = desired.get(kind.kind) ?? []
+      if (!kind.remove || documents.length === 0) continue
+      const wanted = new Set(documents.map((document) => (document as { key: string }).key))
+      const keys = [...kind.existingIds(state).keys()].filter((key) => !wanted.has(key)).sort()
+      if (keys.length) found.set(kind.kind, keys)
+    }
+    return found
+  }
+
+  function plan(state: State, desired: Map<string, unknown[]>, token: ImportOptions<Actor>['token'], prune: boolean) {
+    const problems = new Problems()
+    const resolve = createVaultResolver(options.vaultRows(state))
+    const removals = prune ? stale(state, desired) : new Map<string, string[]>()
+    const ctx: PlanContext<State> = {
+      state, token, problems,
+      resolveVaults: (value, path) => resolve(value, path, problems),
+      desired: (kind) => desired.get(kind) ?? [],
+      removed: (kind) => new Set(removals.get(kind) ?? []),
+    }
+    const planned = new Map<string, unknown>()
+    const changes: ConfigChange[] = []
+    for (const kind of order) {
+      const result = kind.plan(desired.get(kind.kind) ?? [], ctx)
+      planned.set(kind.kind, result.planned)
+      changes.push(...result.changes)
+    }
+    if (problems.any) throw new ConfigInvalidError(problems.list)
+    for (const kind of order) for (const key of removals.get(kind.kind) ?? []) changes.push({ kind: kind.kind, key, action: 'delete' })
+    return { planned, changes, removals }
+  }
+
+  async function execute(state: State, planned: Map<string, unknown>, removals: Map<string, string[]>): Promise<AuditEntry[]> {
+    const ids = new Map(names.map((name) => [name, kinds.get(name)!.existingIds(state)]))
+    const ctx: ApplyContext<State> = { state, now: Date.now(), ids: (kind) => ids.get(kind)! }
+    const audit: AuditEntry[] = []
+    for (const kind of order) audit.push(...await kind.apply(planned.get(kind.kind), ctx))
+    for (const kind of order) await kind.link?.(planned.get(kind.kind), ctx)
+    // Last, and in the reverse order, so that what links to a kind is deleted before the kind.
+    for (const kind of [...order].reverse()) {
+      const keys = removals.get(kind.kind)
+      if (keys) audit.push(...await kind.remove!(keys, ctx))
+    }
+    return audit
+  }
+
+  function summarise(changes: ConfigChange[], prune: boolean): ImportResult['summary'] {
+    const summary: Record<ChangeAction, number> = { create: 0, update: 0, delete: 0, unchanged: 0 }
+    for (const change of changes) summary[change.action] += 1
+    if (!prune) return { create: summary.create, update: summary.update, unchanged: summary.unchanged }
+    return summary
+  }
+
+  /**
+   * Makes the installation match the documents: an object whose key exists is updated, one whose key does not is created.
+   * Nothing is removed unless `prune` is set. Everything is checked before anything is written, and the writes are one transaction, so a
+   * stream is applied completely or not at all. With `dryRun` nothing is written and the result says what would happen.
+   */
+  async function importDocuments(documents: unknown[], importOptions: ImportOptions<Actor>): Promise<ImportResult> {
+    const problems = new Problems()
+    const desired = parseDocuments(documents, problems)
+    if (problems.any) throw new ConfigInvalidError(problems.list)
+
+    const result = (changes: ConfigChange[]): ImportResult => ({ dryRun: importOptions.dryRun, summary: summarise(changes, !!importOptions.prune), changes })
+
+    if (importOptions.dryRun) return result(plan(await options.loadState(), desired, importOptions.token, !!importOptions.prune).changes)
+
+    const { changes, audit } = await options.transaction(async () => {
+      const state = await options.loadState()
+      const { planned, changes, removals } = plan(state, desired, importOptions.token, !!importOptions.prune)
+      const audit = changes.some((change) => change.action !== 'unchanged') ? await execute(state, planned, removals) : []
+      return { changes, audit }
+    })
+
+    // The changes are committed. A failure past this point must not turn a successful import into an error (the
+    // client would retry, and a second apply is a no-op), so it is logged instead.
+    if (audit.length) {
+      try {
+        await options.afterApply?.()
+        for (const entry of audit) await options.audit.write(importOptions.actor, entry.action, entry.entity, entry.id, entry.name, entry.diff)
+        const summary = summarise(changes, !!importOptions.prune)
+        await options.audit.write(importOptions.actor, 'update', options.auditEntity ?? 'config', null, 'Configuration import', {
+          created: summary.create, updated: summary.update, ...(importOptions.prune ? { deleted: summary.delete ?? 0 } : {}), unchanged: summary.unchanged,
+        })
+      } catch (error) {
+        console.error('[config] Imported, but could not finish the follow-up work:', error)
+      }
+    }
+    return result(changes)
+  }
+
+  /**
+   * The documents of every kind, in a fixed order that does not depend on this installation's numeric ids. Secrets are
+   * masked by the kinds, and runtime state is left out. `only` writes out one document; `included` leaves out kinds.
+   */
+  async function exportDocuments(only?: { kind: string; key: string }, exportOptions: { included?: ReadonlySet<string> } = {}): Promise<Json[]> {
+    const included = exportOptions.included ?? new Set(names)
+    const state = await options.loadExportState(included)
+    const ctx: ExportContext = {
+      exportVaultRefs: createVaultExporter(options.exportVaultRows(state)),
+      // Only the rows asked for are written out, so a vault name that is ambiguous for some other object does not matter.
+      wanted: (rows, kind) => (only ? rows.filter((row) => only.kind === kind && row.key === only.key) : rows),
+      included: (kind) => included.has(kind),
+    }
+    return order.filter((kind) => included.has(kind.kind)).flatMap((kind) => kind.export(state, ctx))
+  }
+
+  /** The one document of a kind and key, or undefined when there is none. */
+  function pickDocument(documents: Json[], kind: string, key: string | undefined): Json | undefined {
+    return documents.find((document) => document['kind'] === kind && document['key'] === key)
+  }
+
+  return { kinds: names, kindsIn, importDocuments, exportDocuments, pickDocument }
+}
+
+export type ConfigEngine<State, ExportState, Actor> = ReturnType<typeof createConfigEngine<State, ExportState, Actor>>

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  backfillKeys, ENTITY_KEY_ERROR, ENTITY_KEY_PATTERN, isValidEntityKey, keyForNew, randomEntityKey, slugifyKey,
+  type KeyOwner, type KeyResult,
+} from './keys.js'
+export { MAX_DOCUMENTS, readDocuments, toYaml, toYamlStream } from './yaml.js'
+export {
+  byKey, canonical, clip, ConfigExportError, ConfigInvalidError, createVaultExporter, createVaultResolver, documentKey, findCycle, forbiddenNameAt,
+  isObject, keyList, nestedDeeperThan, Problems, unknownFields,
+  type ConfigProblem, type ConfigVaultRef, type Json, type VaultRows,
+} from './document.js'
+export {
+  createConfigEngine,
+  type ApplyContext, type AuditEntry, type ChangeAction, type ConfigChange, type ConfigEngine, type ConfigEngineOptions, type ConfigKind,
+  type ExportContext, type ImportOptions, type ImportResult, type PlanContext,
+} from './engine.js'
+export { createConfigRoutes, type ConfigCaller, type ConfigRoutesOptions, type KindAccess } from './routes.js'

package/src/keys.ts

@@ -0,0 +1,64 @@
+import type { DatabaseSync } from 'node:sqlite'
+import { randomBytes } from 'node:crypto'
+
+/** Keys appear in config files and URLs: lowercase, digits, `-` and `_`, starting with a letter or digit. */
+export const ENTITY_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/
+export const ENTITY_KEY_ERROR = 'Key must be 1-64 characters: lowercase letters, digits, "-" or "_", starting with a letter or digit'
+
+/** Fallback for rows inserted without a key (the routes derive one from the name instead). */
+export function randomEntityKey(): string {
+  return `k-${randomBytes(5).toString('hex')}`
+}
+
+export function isValidEntityKey(value: unknown): value is string {
+  return typeof value === 'string' && ENTITY_KEY_PATTERN.test(value)
+}
+
+export function slugifyKey(name: string): string {
+  const slug = name
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[łŁ]/g, 'l') // does not decompose into l + diacritic
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+    .replace(/-+$/, '')
+  return slug || 'item'
+}
+
+/** Resolves the id of the row holding `key`, if any. */
+export type KeyOwner = (key: string) => Promise<number | undefined>
+
+export type KeyResult = { key: string } | { status: 400 | 409; error: string }
+
+/** Key for a new row: the requested one when given (validated, must be free), else the first free slug of `name`. */
+export async function keyForNew(name: string, requested: unknown, ownerOf: KeyOwner): Promise<KeyResult> {
+  if (requested !== undefined) {
+    if (!isValidEntityKey(requested)) return { status: 400, error: ENTITY_KEY_ERROR }
+    return (await ownerOf(requested)) === undefined ? { key: requested } : { status: 409, error: `Key "${requested}" is already in use` }
+  }
+  const base = slugifyKey(name)
+  let candidate = base
+  for (let n = 2; (await ownerOf(candidate)) !== undefined; n++) candidate = `${base}-${n}`
+  return { key: candidate }
+}
+
+/**
+ * Gives every row of `tables` that has no key yet one made from its name, in id order, the same way `keyForNew` does
+ * for a new row (`name`, then `name-2`, `name-3`, ...). The tables need `id`, `name` and `key` columns.
+ */
+export function backfillKeys(sqlite: DatabaseSync, tables: readonly string[]): void {
+  for (const table of tables) {
+    const rows = sqlite.prepare(`SELECT id, name FROM ${table} WHERE key = '' ORDER BY id`).all() as Array<{ id: number; name: string }>
+    const taken = new Set((sqlite.prepare(`SELECT key FROM ${table} WHERE key <> ''`).all() as Array<{ key: string }>).map((row) => row.key))
+    const assign = sqlite.prepare(`UPDATE ${table} SET key = ? WHERE id = ?`)
+    for (const { id, name } of rows) {
+      const base = slugifyKey(name)
+      let key = base
+      for (let n = 2; taken.has(key); n++) key = `${base}-${n}`
+      taken.add(key)
+      assign.run(key, id)
+    }
+  }
+}