@huynle/hub 0.6.1 → 0.7.1

package/src/central/import.ts

@@ -0,0 +1,318 @@
+// `hub-server import --state <dir>` (design §10, decision vkxkqiuf): moves a single-process hub's state into the
+// shared StateStore a cluster reads (Postgres), idempotently.
+//
+// - state.json is read through the Store's own load/upgrade code (Store.read: older formats are upgraded, nothing is
+//   written back) and stored as the rows Store.shared reads (stateRows in ./store-shared: records, settings, audit,
+//   token-hash and email index rows). Token hashes are copied, so machines and devices need no re-enrolment.
+// - agent/** (the FileStateStore: per-user collections and claim namespaces) becomes the same rows and claims.
+// - token-keys.json is never stored: the report names its key ids, and tokenKeysMaterial() returns it as the
+//   HUB_TOKEN_KEYS Secret value for the operator (`--print-token-keys`).
+// Every row is inserted with ifVersion 0. A row already there is left alone: unchanged when equal (JSON with keys in
+// any order: Postgres jsonb reorders them), a conflict otherwise, overwritten only with `force`. A dry run reads the
+// target and counts, but writes nothing. The source directory is only read; stop the single-process hub first, so
+// its files are complete.
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+import { AGENT_STATE_DIR, FileStateStore } from "./backend/file-state"
+import type { StateStore } from "./backend/types"
+import { HUB_ROWS, Store, type AuditEntry } from "./store"
+import { nextAuditKey, stateRows } from "./store-shared"
+import { TOKEN_KEYS_ENV, TOKEN_KEYS_FILE, TokenKeys } from "./token-keys"
+
+export interface ImportOptions {
+  /** The single-process hub's state directory (state.json, agent/, token-keys.json). */
+  readonly stateDir: string
+  /** Where the rows go (Postgres in a cluster). */
+  readonly state: StateStore
+  /** Count only; write nothing. */
+  readonly dryRun?: boolean
+  /** Overwrite rows (and claims) that exist with different contents. */
+  readonly force?: boolean
+  /**
+   * The clock of the state.json upgrade (default: state.json's modification time, so records the upgrade adds, like
+   * the local owner, come out the same on every run).
+   */
+  readonly now?: () => number
+}
+
+/** Per collection: rows read from the source and what happened to them (in a dry run: would happen). */
+export interface CollectionCounts {
+  rows: number
+  /** Not there yet: written. */
+  created: number
+  /** Already there with the same contents. */
+  unchanged: number
+  /** Already there with other contents (skipped unless forced). */
+  conflicts: number
+  /** Conflicts written over (force). */
+  overwritten: number
+  failed: number
+}
+
+export interface ImportReport {
+  readonly stateDir: string
+  readonly dryRun: boolean
+  readonly force: boolean
+  /** Whether state.json was there. */
+  readonly stateFile: boolean
+  /** Agent StateStore files read (collections and claim namespaces). */
+  readonly agentFiles: number
+  /** By collection: the Store's ("users", …), agent ones as "agent:<collection>", claims as "claims:<namespace>". */
+  readonly collections: Record<string, CollectionCounts>
+  /** The rows that differ: "<collection> <user>/<key>". */
+  readonly conflicts: string[]
+  /** Rows that could not be written, with the reason (never a value). */
+  readonly failures: { readonly row: string; readonly error: string }[]
+  readonly failed: number
+  /** The signing keys found (ids only), or undefined without token-keys.json. */
+  readonly tokenKeys?: { readonly active: string; readonly kids: string[] }
+}
+
+/** One row (or claim) to import. */
+interface Item {
+  readonly collection: string
+  readonly label: string
+  /** What the target holds: absent, equal or different (with what to compare-and-set against). */
+  inspect(): Promise<{ readonly state: "absent" } | { readonly state: "same" } | { readonly state: "differs"; readonly version: number; readonly owner?: string }>
+  /** Inserts it; false when someone else wrote it meanwhile. */
+  create(): Promise<boolean>
+  /** Writes it over the differing row seen by inspect; false when it changed meanwhile. */
+  overwrite(seen: { readonly version: number; readonly owner?: string }): Promise<boolean>
+}
+
+/** Imports the state directory into `options.state`; see the file comment. */
+export async function importState(options: ImportOptions): Promise<ImportReport> {
+  const { stateDir, state: target } = options
+  const dryRun = options.dryRun === true
+  const force = options.force === true
+  const agentRoot = path.join(stateDir, AGENT_STATE_DIR)
+  const stateFile = existsSync(path.join(stateDir, "state.json"))
+  if (!stateFile && !existsSync(agentRoot)) throw new Error(`No hub state in ${stateDir} (neither state.json nor ${AGENT_STATE_DIR}/)`)
+
+  const items: Item[] = []
+  // Store rows: state.json upgraded by the Store's own code, mapped by the shared Store's own row layout.
+  const stateMtime = stateFile ? Math.floor(statSync(path.join(stateDir, "state.json")).mtimeMs) : 0
+  const data = Store.read(stateDir, options.now ?? (() => stateMtime))
+  if (data) {
+    const keys = auditKeys(data.audit)
+    for (const row of stateRows(data, (entry) => keys.get(entry)!)) items.push(rowItem(target, row.collection, HUB_ROWS, row.collection, row.key, row.value))
+  }
+  // Agent rows and claims, read through the FileStateStore (it checks each file belongs to its ids).
+  const source = new FileStateStore({ stateDir })
+  const files = agentFiles(agentRoot)
+  for (const { userID, collection } of files.collections) {
+    for (const entry of await source.list(userID, collection)) items.push(rowItem(target, `agent:${collection}`, userID, collection, entry.key, entry.value))
+  }
+  for (const { namespace, keys } of files.claims) {
+    for (const key of keys) {
+      const claim = await source.claimOf(namespace, key)
+      if (claim) items.push(claimItem(target, namespace, key, claim.owner))
+    }
+  }
+
+  const collections: Record<string, CollectionCounts> = {}
+  const conflicts: string[] = []
+  const failures: { row: string; error: string }[] = []
+  for (const item of items) {
+    const counts = (collections[item.collection] ??= { rows: 0, created: 0, unchanged: 0, conflicts: 0, overwritten: 0, failed: 0 })
+    counts.rows++
+    try {
+      const seen = await item.inspect()
+      if (seen.state === "same") counts.unchanged++
+      else if (seen.state === "absent") {
+        if (dryRun || (await item.create())) counts.created++
+        else {
+          counts.failed++
+          failures.push({ row: item.label, error: "written by someone else during the import" })
+        }
+      } else {
+        counts.conflicts++
+        conflicts.push(item.label)
+        if (!force) continue
+        if (dryRun || (await item.overwrite(seen))) counts.overwritten++
+        else {
+          counts.failed++
+          failures.push({ row: item.label, error: "changed by someone else during the import" })
+        }
+      }
+    } catch (error) {
+      counts.failed++
+      failures.push({ row: item.label, error: (error as Error)?.message ?? String(error) })
+    }
+  }
+
+  const keys = readTokenKeys(stateDir)
+  return {
+    stateDir,
+    dryRun,
+    force,
+    stateFile,
+    agentFiles: files.collections.length + files.claims.length,
+    collections,
+    conflicts,
+    failures,
+    failed: failures.length,
+    ...(keys ? { tokenKeys: { active: keys.active, kids: keys.kids } } : {}),
+  }
+}
+
+/**
+ * The signing keys of the state directory as the HUB_TOKEN_KEYS Secret value (one JSON line), validated; undefined
+ * without token-keys.json. Secret material: print it only when asked, never log or store it.
+ */
+export function tokenKeysMaterial(stateDir: string): string | undefined {
+  return readTokenKeys(stateDir)?.material
+}
+
+function readTokenKeys(stateDir: string): { material: string; active: string; kids: string[] } | undefined {
+  const file = path.join(stateDir, TOKEN_KEYS_FILE)
+  if (!existsSync(file)) return undefined
+  const text = readFileSync(file, "utf8")
+  // Validated by TokenKeys itself (given as the override, so it never touches the file); errors name no secret.
+  const keys = TokenKeys.open(stateDir, { env: { [TOKEN_KEYS_ENV]: text } })
+  let kids: string[]
+  try {
+    kids = keys.kids()
+  } catch (error) {
+    throw new Error(((error as Error).message ?? "").replace(TOKEN_KEYS_ENV, file))
+  }
+  return { material: JSON.stringify(JSON.parse(text)), active: keys.toJSON().active, kids }
+}
+
+/**
+ * Stable row keys for the audit entries (in order): the shared Store's key layout, with a suffix derived from the
+ * entry and its position instead of a random one, so a second import finds the same rows.
+ */
+function auditKeys(audit: readonly AuditEntry[]): Map<AuditEntry, string> {
+  const keys = new Map<AuditEntry, string>()
+  let last: string | undefined
+  audit.forEach((entry, index) => {
+    const suffix = createHash("sha256").update(`${index}\n${JSON.stringify(entry)}`).digest("hex").slice(0, 8)
+    last = nextAuditKey(last, entry.at, suffix)
+    keys.set(entry, last)
+  })
+  return keys
+}
+
+/** The agent StateStore files: per-user collections and claim namespaces, from the ids each file repeats. */
+function agentFiles(root: string): { collections: { userID: string; collection: string }[]; claims: { namespace: string; keys: string[] }[] } {
+  const collections: { userID: string; collection: string }[] = []
+  const claims: { namespace: string; keys: string[] }[] = []
+  const json = (dir: string) => (existsSync(dir) ? readdirSync(dir).filter((name) => name.endsWith(".json")).sort().map((name) => path.join(dir, name)) : [])
+  const users = path.join(root, "users")
+  const userDirs = existsSync(users) ? readdirSync(users, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort() : []
+  for (const dir of userDirs) {
+    for (const file of json(path.join(users, dir))) {
+      const { userID, collection } = header(file)
+      if (typeof userID !== "string" || typeof collection !== "string") throw new Error(`Invalid ${file}: no userID or collection. Fix or move it away.`)
+      collections.push({ userID, collection })
+    }
+  }
+  for (const file of json(path.join(root, "claims"))) {
+    const { namespace, items } = header(file)
+    if (typeof namespace !== "string" || !Array.isArray(items)) throw new Error(`Invalid ${file}: no namespace or items. Fix or move it away.`)
+    claims.push({ namespace, keys: items.map((item) => (item as { key?: unknown })?.key).filter((key): key is string => typeof key === "string") })
+  }
+  return { collections, claims }
+}
+
+function header(file: string): Record<string, unknown> {
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8")) as unknown
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) return raw as Record<string, unknown>
+  } catch {
+    // Reported below without the content.
+  }
+  throw new Error(`Invalid ${file}: not a JSON object. Fix or move it away.`)
+}
+
+function rowItem(target: StateStore, label: string, userID: string, collection: string, key: string, value: unknown): Item {
+  return {
+    collection: label,
+    label: `${label} ${userID}/${key}`,
+    async inspect() {
+      const current = await target.get(userID, collection, key)
+      if (!current) return { state: "absent" }
+      return canonical(current.value) === canonical(value) ? { state: "same" } : { state: "differs", version: current.version }
+    },
+    async create() {
+      return (await target.put(userID, collection, key, value, { ifVersion: 0 })).ok
+    },
+    async overwrite(seen) {
+      return (await target.put(userID, collection, key, value, { ifVersion: seen.version })).ok
+    },
+  }
+}
+
+function claimItem(target: StateStore, namespace: string, key: string, owner: string): Item {
+  return {
+    collection: `claims:${namespace}`,
+    label: `claims:${namespace} ${key}`,
+    async inspect() {
+      const current = await target.claimOf(namespace, key)
+      if (!current) return { state: "absent" }
+      return current.owner === owner ? { state: "same" } : { state: "differs", version: 0, owner: current.owner }
+    },
+    async create() {
+      return (await target.claim(namespace, key, owner)).ok
+    },
+    async overwrite(seen) {
+      if (!(await target.release(namespace, key, seen.owner!))) return false
+      return (await target.claim(namespace, key, owner)).ok
+    },
+  }
+}
+
+/** JSON with object keys sorted (Postgres jsonb does not keep their order). */
+function canonical(value: unknown): string {
+  const sort = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(sort)
+    if (typeof v === "object" && v !== null) {
+      return Object.fromEntries(
+        Object.keys(v)
+          .sort()
+          .map((k) => [k, sort((v as Record<string, unknown>)[k])]),
+      )
+    }
+    return v
+  }
+  return JSON.stringify(sort(JSON.parse(JSON.stringify(value ?? null))))
+}
+
+/** The report as lines for the terminal (no secrets: key ids only). */
+export function formatImportReport(report: ImportReport): string[] {
+  const lines = [
+    `Import from ${report.stateDir}${report.dryRun ? " (dry run: nothing written)" : ""}${report.force ? " with --force" : ""}`,
+    `  state.json: ${report.stateFile ? "read" : "none"}; agent files: ${report.agentFiles}`,
+  ]
+  const columns = ["rows", "new", "same", "conflict", "overwritten", "failed"] as const
+  const names = Object.keys(report.collections)
+  const width = Math.max(10, ...names.map((name) => name.length))
+  const row = (name: string, cells: readonly (string | number)[]) => `  ${name.padEnd(width)}  ${cells.map((cell) => String(cell).padStart(12)).join("")}`
+  lines.push(row("collection", columns))
+  const totals = [0, 0, 0, 0, 0, 0]
+  for (const name of names) {
+    const c = report.collections[name]!
+    const cells = [c.rows, c.created, c.unchanged, c.conflicts, c.overwritten, c.failed]
+    cells.forEach((n, i) => (totals[i]! += n))
+    lines.push(row(name, cells))
+  }
+  lines.push(row("total", totals))
+  if (report.conflicts.length) {
+    lines.push(`Conflicts (rows already there with other contents; ${report.force ? "overwritten" : "skipped, rerun with --force to overwrite"}):`)
+    for (const conflict of report.conflicts) lines.push(`  ${conflict}`)
+  }
+  if (report.failures.length) {
+    lines.push("Failed:")
+    for (const failure of report.failures) lines.push(`  ${failure.row}: ${failure.error}`)
+  }
+  if (report.tokenKeys) {
+    lines.push(
+      `Signing keys (token-keys.json): ${report.tokenKeys.kids.join(", ")} (active ${report.tokenKeys.active}); not stored. Put them in the HUB_TOKEN_KEYS Secret so signed-in sessions stay valid: rerun with --print-token-keys to print the value.`,
+    )
+  } else {
+    lines.push("Signing keys: no token-keys.json; set a new HUB_TOKEN_KEYS (browsers and apps sign in again; machines and devices keep their tokens).")
+  }
+  return lines
+}

package/src/central/main.ts

@@ -3,19 +3,58 @@
 import type { WebAssets } from "./assets"
 import { PAIR_TTL_MS } from "./auth"
 import { isLoopbackURL } from "../loopback"
-import { loadCentralConfig, type CentralConfig } from "./config"
+import { SQL } from "bun"
+import { homedir } from "node:os"
+import type { StateStore } from "./backend"
+import { migrate, type MigrateResult } from "./backend/postgres-migrate"
+import { PostgresStateStore } from "./backend/postgres-state"
+import { hubConfigPath, loadCentralConfig, readHubFile, type CentralConfig } from "./config"
 import { startCentral } from "./http"
+import { formatImportReport, importState, tokenKeysMaterial } from "./import"
 
-export type HubArgs = { readonly action: "run" | "version" | "help" } | { readonly action: "error"; readonly message: string }
+export interface ImportArgs {
+  readonly stateDir: string
+  readonly dryRun: boolean
+  readonly force: boolean
+  readonly printTokenKeys: boolean
+}
+
+export type HubArgs =
+  | { readonly action: "run" | "version" | "help" | "migrate" }
+  | ({ readonly action: "import" } & ImportArgs)
+  | { readonly action: "error"; readonly message: string }
 
 export function parseHubArgs(argv: readonly string[]): HubArgs {
   if (argv.length === 0) return { action: "run" }
   const [first] = argv
   if (argv.length === 1 && (first === "--version" || first === "-v")) return { action: "version" }
   if (argv.length === 1 && (first === "--help" || first === "-h")) return { action: "help" }
+  if (argv.length === 1 && first === "migrate") return { action: "migrate" }
+  if (first === "import") return parseImportArgs(argv.slice(1))
   return { action: "error", message: `Unknown argument: ${argv.join(" ")}. The hub is configured with env vars and hub.json; see --help.` }
 }
 
+function parseImportArgs(argv: readonly string[]): HubArgs {
+  const usage = "Usage: hub-server import --state <dir> [--dry-run] [--force] [--print-token-keys]"
+  let stateDir: string | undefined
+  const flags = { dryRun: false, force: false, printTokenKeys: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!
+    const inline = arg.startsWith("--state=") ? arg.slice("--state=".length) : undefined
+    if (arg === "--state" || inline !== undefined) {
+      const value = inline ?? argv[++i]
+      if (!value || value.startsWith("--")) return { action: "error", message: `--state needs a directory. ${usage}` }
+      if (stateDir !== undefined) return { action: "error", message: `--state given twice. ${usage}` }
+      stateDir = value
+    } else if (arg === "--dry-run") flags.dryRun = true
+    else if (arg === "--force") flags.force = true
+    else if (arg === "--print-token-keys") flags.printTokenKeys = true
+    else return { action: "error", message: `Unknown import argument: ${arg}. ${usage}` }
+  }
+  if (stateDir === undefined) return { action: "error", message: `import needs --state <dir> (the single-process hub's state directory). ${usage}` }
+  return { action: "import", stateDir, ...flags }
+}
+
 export function hubHelp(version: string): string {
   return `hub-server ${version}
 
@@ -23,6 +62,8 @@ Hub: the central hub your AI agent harnesses connect to (OpenCode first). Serves
 pairs phones and browsers, enrolls machines, and does push notifications and (optional) Voice speech.
 
 Usage: hub-server [--help | --version]   (also installed as opencode-hub and opencode-voice-hub)
+       hub-server migrate
+       hub-server import --state <dir> [--dry-run] [--force] [--print-token-keys]
 
 Configuration: environment variables over ~/.config/hub/hub.json ($HUB_CONFIG).
   HUB_HOST / HUB_PORT       listen address (default 127.0.0.1 / 4097)
@@ -40,6 +81,14 @@ Multi-user (sign in with Google or another OpenID Connect provider):
   HUB_ADMIN_EMAILS          admin emails, comma separated (at least one)
   Register <public URL>/auth/callback as the redirect URI.
 
+Cluster mode (several pods on Postgres + Valkey; docs/cluster.md):
+  HUB_DATABASE_URL / HUB_VALKEY_URL   postgres:// and redis:// URLs (both, or hub.json cluster)
+  migrate                   applies the Postgres schema (idempotent, under an advisory lock); run it before the pods
+  import --state <dir>      copies a single-process hub's state directory (state.json, agent/) into Postgres;
+                            idempotent: existing rows are kept (conflicts listed) unless --force; --dry-run writes
+                            nothing; --print-token-keys prints token-keys.json as the HUB_TOKEN_KEYS value (secret)
+                            on stdout. Stop the single-process hub first. Machines and devices keep their tokens.
+
 The former VOICE_* names (opencode-voice) still work, with a deprecation warning; so do the
 opencode-hub and opencode-voice config and state directories (copied once on first start).
 While no device is paired, the log shows a pairing code for the first one (open <public URL>/pair).
@@ -86,6 +135,12 @@ export function runHub(options: RunHubOptions): void {
     console.error(`[hub] ${args.message}`)
     process.exit(2)
   }
+  if (args.action === "migrate" || args.action === "import") {
+    const io: CommandIO = { env: process.env, out: (line) => console.log(line), err: (line) => console.error(line) }
+    const run = args.action === "import" ? runImport(args, io) : runMigrate(io)
+    void run.then((code) => process.exit(code))
+    return
+  }
 
   let loaded: ReturnType<typeof loadCentralConfig>
   try {
@@ -122,15 +177,159 @@ export function runHub(options: RunHubOptions): void {
     }, PAIR_TTL_MS - 5_000)
   }
 
-  let stopping = false
-  const shutdown = async (signal: string) => {
-    if (stopping) return
-    stopping = true
-    console.log(`[hub] ${signal}: shutting down`)
-    clearInterval(timer)
-    await central.stop()
-    process.exit(0)
+  const onSignal = shutdownOnSignals(central, {
+    log: (line) => {
+      clearInterval(timer)
+      console.log(line)
+    },
+    exit: (code) => process.exit(code),
+  })
+  process.on("SIGTERM", () => void onSignal("SIGTERM"))
+  process.on("SIGINT", () => void onSignal("SIGINT"))
+}
+
+/**
+ * The hub's signal handler: the first SIGTERM/SIGINT shuts down (shutdownHub) and exits 0; a second one while that is
+ * still running (a drain waiting for requests) stops at once and exits 1; later ones are ignored.
+ */
+export function shutdownOnSignals(
+  central: { drain(): Promise<void>; stop(): Promise<void> },
+  options: { readonly log: (line: string) => void; readonly exit: (code: number) => void },
+): (signal: string) => Promise<void> {
+  let state: "running" | "stopping" | "forced" = "running"
+  return async (signal) => {
+    if (state === "forced") return
+    if (state === "stopping") {
+      state = "forced"
+      options.log(`[hub] ${signal} again: stopping now`)
+      await central.stop().catch((cause: unknown) => options.log(`[hub] stop failed: ${(cause as Error)?.message ?? cause}`))
+      options.exit(1)
+      return
+    }
+    state = "stopping"
+    // Once forced, the drain ending later neither stops again nor exits.
+    const once = { drain: () => central.drain(), stop: () => (state === "forced" ? Promise.resolve() : central.stop()) }
+    await shutdownHub(once, signal, options.log)
+    if (state === "stopping") options.exit(0)
+  }
+}
+
+/**
+ * Shuts the hub down on a signal. SIGTERM (Kubernetes replacing the pod, systemd, docker stop) drains first (design
+ * §10: /readyz fails, spokes and nodes are sent to another pod, requests in flight finish; quick without any), then
+ * stops; SIGINT (Ctrl-C) stops at once. A failed drain still stops.
+ */
+export async function shutdownHub(central: { drain(): Promise<void>; stop(): Promise<void> }, signal: string, log: (line: string) => void = console.log): Promise<void> {
+  if (signal === "SIGTERM") {
+    log(`[hub] ${signal}: draining`)
+    try {
+      await central.drain()
+    } catch (cause) {
+      log(`[hub] drain failed: ${cause instanceof Error ? cause.message : cause}`)
+    }
+  }
+  log(`[hub] ${signal}: shutting down`)
+  await central.stop()
+}
+
+
+/** Where the one-shot commands (migrate, import) read settings and write lines. */
+export interface CommandIO {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly out: (line: string) => void
+  readonly err: (line: string) => void
+  /** For the hub.json path (default the user's home). */
+  readonly home?: string
+}
+
+/**
+ * The Postgres URL of the one-shot commands: HUB_DATABASE_URL, else hub.json cluster.database. Errors name the
+ * setting, never the value (it holds the password).
+ */
+function databaseURL(io: CommandIO): string {
+  const name = "HUB_DATABASE_URL (cluster.database)"
+  const url = io.env.HUB_DATABASE_URL?.trim() || readHubFile(hubConfigPath(io.env, io.home ?? homedir()), io.home ?? homedir()).file?.cluster?.database
+  if (!url) throw new Error(`${name} is not set: the Postgres database of the cluster`)
+  let protocol: string
+  try {
+    protocol = new URL(url).protocol
+  } catch {
+    throw new Error(`${name} is not a valid URL`)
+  }
+  if (protocol !== "postgres:" && protocol !== "postgresql:") throw new Error(`${name} must be a postgres:// or postgresql:// URL`)
+  return url
+}
+
+/** A message without the URL or its secret-ish parts (password, host). */
+function redact(message: string, url: string | undefined): string {
+  if (!url) return message
+  let out = message.split(url).join("<database>")
+  try {
+    const parsed = new URL(url)
+    for (const part of [parsed.password, decodeURIComponent(parsed.password), parsed.host, parsed.hostname]) {
+      if (part && part.length >= 3) out = out.split(part).join("<redacted>")
+    }
+  } catch {
+    // Not a URL: nothing more to hide.
+  }
+  return out
+}
+
+/** `hub-server migrate`: applies the Postgres schema (idempotent, under the advisory lock). Returns the exit code. */
+export async function runMigrate(io: CommandIO & { readonly migrate?: (url: string) => Promise<MigrateResult> }): Promise<number> {
+  let url: string | undefined
+  try {
+    url = databaseURL(io)
+    const result = await (io.migrate ?? migrateDatabase)(url)
+    io.out(
+      result.applied.length
+        ? `[hub] migrate: applied ${result.applied.join(", ")}; schema now at version ${result.version}`
+        : `[hub] migrate: schema up to date at version ${result.version}`,
+    )
+    return 0
+  } catch (cause) {
+    io.err(`[hub] migrate failed: ${redact((cause as Error)?.message ?? String(cause), url)}`)
+    return 1
+  }
+}
+
+async function migrateDatabase(url: string): Promise<MigrateResult> {
+  const sql = new SQL(url, { max: 1 })
+  try {
+    return await migrate(sql)
+  } finally {
+    await sql.close().catch(() => {})
+  }
+}
+
+/**
+ * `hub-server import`: the state directory into Postgres (see ./import). The report goes to stdout, or to stderr with
+ * --print-token-keys, so stdout holds only the HUB_TOKEN_KEYS value. Returns the exit code (1 when a row failed).
+ */
+export async function runImport(
+  args: ImportArgs,
+  io: CommandIO & { readonly openState?: (url: string) => StateStore & { close?(): Promise<void> } },
+): Promise<number> {
+  const report = args.printTokenKeys ? io.err : io.out
+  let url: string | undefined
+  let state: (StateStore & { close?(): Promise<void> }) | undefined
+  try {
+    url = databaseURL(io)
+    state = (io.openState ?? ((u: string) => new PostgresStateStore({ url: u, max: 2 })))(url)
+    // Reachable and migrated (a schema error says to run migrate), before any row is read or counted.
+    await state.ping?.()
+    const result = await importState({ stateDir: args.stateDir, state, dryRun: args.dryRun, force: args.force })
+    for (const line of formatImportReport(result)) report(redact(line, url))
+    if (args.printTokenKeys) {
+      const material = tokenKeysMaterial(args.stateDir)
+      if (material) io.out(material)
+      else io.err("[hub] no token-keys.json: nothing to print")
+    }
+    return result.failed ? 1 : 0
+  } catch (cause) {
+    io.err(`[hub] import failed: ${redact((cause as Error)?.message ?? String(cause), url)}`)
+    return 1
+  } finally {
+    await state?.close?.().catch(() => {})
   }
-  process.on("SIGTERM", () => void shutdown("SIGTERM"))
-  process.on("SIGINT", () => void shutdown("SIGINT"))
 }