@brainjar/cli 0.2.3 → 0.4.0

package/src/config.ts

@@ -0,0 +1,125 @@
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { getBrainjarDir, paths } from './paths.js'
+import type { Backend } from './paths.js'
+
+export interface ServerConfig {
+  url: string
+  mode: 'local' | 'remote'
+  bin: string
+  pid_file: string
+  log_file: string
+}
+
+export interface Config {
+  server: ServerConfig
+  workspace: string
+  backend: Backend
+}
+
+function defaults(): Config {
+  const dir = getBrainjarDir()
+  return {
+    server: {
+      url: 'http://localhost:7742',
+      mode: 'local',
+      bin: `${dir}/bin/brainjar-server`,
+      pid_file: `${dir}/server.pid`,
+      log_file: `${dir}/server.log`,
+    },
+    workspace: 'default',
+    backend: 'claude',
+  }
+}
+
+function isValidMode(v: unknown): v is 'local' | 'remote' {
+  return v === 'local' || v === 'remote'
+}
+
+function isValidBackend(v: unknown): v is Backend {
+  return v === 'claude' || v === 'codex'
+}
+
+/**
+ * Read config from ~/.brainjar/config.yaml.
+ * Returns defaults if file doesn't exist.
+ * Applies env var overrides on top.
+ * Throws if file exists but is corrupt YAML.
+ */
+export async function readConfig(): Promise<Config> {
+  const def = defaults()
+  let config = { ...def, server: { ...def.server } }
+
+  try {
+    const raw = await readFile(paths.config, 'utf-8')
+    let parsed: unknown
+    try {
+      parsed = parseYaml(raw)
+    } catch (e) {
+      throw new Error(`config.yaml is corrupt: ${(e as Error).message}`)
+    }
+
+    if (parsed && typeof parsed === 'object') {
+      const p = parsed as Record<string, unknown>
+
+      if (typeof p.workspace === 'string') config.workspace = p.workspace
+      if (isValidBackend(p.backend)) config.backend = p.backend
+
+      if (p.server && typeof p.server === 'object') {
+        const s = p.server as Record<string, unknown>
+        if (typeof s.url === 'string') config.server.url = s.url
+        if (isValidMode(s.mode)) config.server.mode = s.mode
+        if (typeof s.bin === 'string') config.server.bin = s.bin
+        if (typeof s.pid_file === 'string') config.server.pid_file = s.pid_file
+        if (typeof s.log_file === 'string') config.server.log_file = s.log_file
+      }
+    }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return applyEnvOverrides(config)
+    throw e
+  }
+
+  return applyEnvOverrides(config)
+}
+
+function applyEnvOverrides(config: Config): Config {
+  const url = process.env.BRAINJAR_SERVER_URL
+  if (typeof url === 'string' && url) config.server.url = url
+
+  const workspace = process.env.BRAINJAR_WORKSPACE
+  if (typeof workspace === 'string' && workspace) config.workspace = workspace
+
+  const backend = process.env.BRAINJAR_BACKEND
+  if (isValidBackend(backend)) config.backend = backend
+
+  return config
+}
+
+/**
+ * Write config to ~/.brainjar/config.yaml.
+ * Atomic write (tmp + rename).
+ */
+export async function writeConfig(config: Config): Promise<void> {
+  const doc = {
+    server: {
+      url: config.server.url,
+      mode: config.server.mode,
+      bin: config.server.bin,
+      pid_file: config.server.pid_file,
+      log_file: config.server.log_file,
+    },
+    workspace: config.workspace,
+    backend: config.backend,
+  }
+
+  await mkdir(dirname(paths.config), { recursive: true })
+  const tmp = `${paths.config}.tmp`
+  await writeFile(tmp, stringifyYaml(doc))
+  await rename(tmp, paths.config)
+}
+
+/** Get the config file path. */
+export function getConfigPath(): string {
+  return paths.config
+}

package/src/daemon.ts

@@ -0,0 +1,404 @@
+import { spawn, execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFile, writeFile, rm, access, open, chmod, mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { Errors } from 'incur'
+import { readConfig } from './config.js'
+import { ErrorCode, createError } from './errors.js'
+
+export const DIST_BASE = 'https://get.brainjar.sh/brainjar-server'
+
+const { IncurError } = Errors
+
+export interface HealthStatus {
+  healthy: boolean
+  url: string
+  latencyMs?: number
+  error?: string
+}
+
+export interface DaemonStatus {
+  mode: 'local' | 'remote'
+  url: string
+  running: boolean
+  pid: number | null
+  healthy: boolean
+}
+
+/**
+ * Check if the server is healthy.
+ * Returns health status without throwing.
+ */
+export async function healthCheck(options?: { timeout?: number; url?: string }): Promise<HealthStatus> {
+  const config = await readConfig()
+  const url = options?.url ?? config.server.url
+  const timeout = options?.timeout ?? 2000
+  const start = Date.now()
+
+  try {
+    const response = await fetch(`${url}/healthz`, {
+      signal: AbortSignal.timeout(timeout),
+    })
+    const latencyMs = Date.now() - start
+
+    if (response.status === 200) {
+      try {
+        const body = await response.json() as { status?: string }
+        if (body.status === 'ok') {
+          return { healthy: true, url, latencyMs }
+        }
+      } catch {}
+      return { healthy: true, url, latencyMs }
+    }
+
+    return { healthy: false, url, error: `Server returned ${response.status}` }
+  } catch (e) {
+    return { healthy: false, url, error: (e as Error).message }
+  }
+}
+
+/** Read PID from pid_file, return null if missing or unreadable. */
+async function readPid(pidFile: string): Promise<number | null> {
+  try {
+    const raw = await readFile(pidFile, 'utf-8')
+    const pid = parseInt(raw.trim(), 10)
+    return Number.isFinite(pid) ? pid : null
+  } catch {
+    return null
+  }
+}
+
+/** Check if a process is alive. */
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Remove stale PID file if process is dead. Returns true if PID file was stale. */
+async function cleanStalePid(pidFile: string): Promise<boolean> {
+  const pid = await readPid(pidFile)
+  if (pid === null) return false
+  if (!isAlive(pid)) {
+    await rm(pidFile, { force: true })
+    return true
+  }
+  return false
+}
+
+function detectPlatform(): { os: string; arch: string } {
+  const platform = process.platform
+  const arch = process.arch
+
+  const osMap: Record<string, string> = { darwin: 'darwin', linux: 'linux' }
+  const archMap: Record<string, string> = { arm64: 'arm64', x64: 'amd64' }
+
+  const os = osMap[platform]
+  const mapped = archMap[arch]
+
+  if (!os || !mapped) {
+    throw createError(ErrorCode.BINARY_NOT_FOUND, {
+      message: `Unsupported platform: ${platform}/${arch}. Supported: darwin/linux × amd64/arm64.`,
+    })
+  }
+
+  return { os, arch: mapped }
+}
+
+/**
+ * Fetch the latest server version from the distribution endpoint.
+ */
+export async function fetchLatestVersion(distBase: string = DIST_BASE): Promise<string> {
+  const response = await fetch(`${distBase}/latest`)
+  if (!response.ok) {
+    throw createError(ErrorCode.BINARY_NOT_FOUND, {
+      message: `Failed to fetch latest server version: HTTP ${response.status}`,
+      hint: 'Check your network connection or try again later.',
+    })
+  }
+  return (await response.text()).trim()
+}
+
+/**
+ * Download a tarball, verify its SHA-256 checksum, and extract the binary.
+ * Exported for testing — ensureBinary() is the public entry point.
+ */
+export async function downloadAndVerify(binPath: string, versionBase: string): Promise<void> {
+  const { os, arch } = detectPlatform()
+  const tarballName = `brainjar-server-${os}-${arch}.tar.gz`
+  const tarballUrl = `${versionBase}/${tarballName}`
+  const checksumsUrl = `${versionBase}/checksums.txt`
+
+  await mkdir(dirname(binPath), { recursive: true })
+
+  const [checksumsResponse, tarballResponse] = await Promise.all([
+    fetch(checksumsUrl),
+    fetch(tarballUrl),
+  ])
+
+  if (!tarballResponse.ok) {
+    throw createError(ErrorCode.BINARY_NOT_FOUND, {
+      message: `Failed to download server binary: HTTP ${tarballResponse.status} from ${tarballUrl}`,
+      hint: `Download manually from ${versionBase} and place at ${binPath}`,
+    })
+  }
+
+  const buffer = Buffer.from(await tarballResponse.arrayBuffer())
+
+  if (checksumsResponse.ok) {
+    const checksumsText = await checksumsResponse.text()
+    const expectedHash = checksumsText
+      .split('\n')
+      .find(line => line.includes(tarballName))
+      ?.split(/\s+/)[0]
+
+    if (expectedHash) {
+      const actualHash = createHash('sha256').update(buffer).digest('hex')
+      if (actualHash !== expectedHash) {
+        throw createError(ErrorCode.BINARY_NOT_FOUND, {
+          message: `Checksum mismatch for ${tarballName}: expected ${expectedHash}, got ${actualHash}`,
+          hint: 'The download may be corrupted. Retry, or download manually.',
+        })
+      }
+    }
+  }
+
+  // Extract tarball to a temp dir, then move the binary into place
+  const tmpDir = join(tmpdir(), `brainjar-dl-${Date.now()}`)
+  const tarPath = join(tmpDir, tarballName)
+  await mkdir(tmpDir, { recursive: true })
+  await writeFile(tarPath, buffer)
+
+  try {
+    execFileSync('tar', ['xzf', tarPath, '-C', tmpDir])
+    const extractedBin = join(tmpDir, 'brainjar-server')
+
+    // Verify the binary was extracted
+    try {
+      await access(extractedBin)
+    } catch {
+      throw createError(ErrorCode.BINARY_NOT_FOUND, {
+        message: `Tarball did not contain expected brainjar-server binary`,
+      })
+    }
+
+    const binContent = await readFile(extractedBin)
+    await writeFile(binPath, binContent)
+    await chmod(binPath, 0o755)
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Ensure the server binary exists at the configured path.
+ * Fetches latest version from get.brainjar.sh, downloads tarball, verifies checksum.
+ */
+export async function ensureBinary(): Promise<void> {
+  const config = await readConfig()
+  const binPath = config.server.bin
+
+  try {
+    await access(binPath)
+    return
+  } catch {}
+
+  const { setInstalledServerVersion } = await import('./version-check.js')
+  const version = await fetchLatestVersion()
+  const versionBase = `${DIST_BASE}/${version}`
+  await downloadAndVerify(binPath, versionBase)
+  await setInstalledServerVersion(version)
+}
+
+/**
+ * Download the latest server binary, replacing any existing one.
+ * Returns the version that was installed.
+ */
+export async function upgradeServer(): Promise<{ version: string; alreadyLatest: boolean }> {
+  const { getInstalledServerVersion, setInstalledServerVersion } = await import('./version-check.js')
+  const config = await readConfig()
+  const binPath = config.server.bin
+
+  const version = await fetchLatestVersion()
+  const installed = await getInstalledServerVersion()
+
+  if (installed === version) {
+    return { version, alreadyLatest: true }
+  }
+
+  const versionBase = `${DIST_BASE}/${version}`
+  await downloadAndVerify(binPath, versionBase)
+  await setInstalledServerVersion(version)
+  return { version, alreadyLatest: false }
+}
+
+/**
+ * Start the server daemon.
+ * Spawns the binary in detached mode, writes PID file.
+ */
+export async function start(): Promise<{ pid: number }> {
+  const config = await readConfig()
+  const { bin, pid_file, log_file, url } = config.server
+
+  try {
+    await access(bin)
+  } catch {
+    throw createError(ErrorCode.BINARY_NOT_FOUND, {
+      message: `Server binary not found at ${bin}`,
+    })
+  }
+
+  // Extract port from URL
+  let port: string
+  try {
+    port = new URL(url).port || '7742'
+  } catch {
+    port = '7742'
+  }
+
+  const logFd = await open(log_file, 'a')
+
+  const child = spawn(bin, [], {
+    detached: true,
+    stdio: ['ignore', logFd.fd, logFd.fd],
+    env: { ...process.env, PORT: port, BRAINJAR_POSTGRES_EMBEDDED: 'true' },
+  })
+
+  const pid = child.pid
+  if (!pid) {
+    await logFd.close()
+    throw createError(ErrorCode.SERVER_START_FAILED, {
+      message: 'Failed to start brainjar server — no PID returned.',
+      hint: `Check ${log_file}`,
+    })
+  }
+
+  child.unref()
+  await logFd.close()
+  await writeFile(pid_file, String(pid))
+
+  return { pid }
+}
+
+/**
+ * Stop the server daemon.
+ * Sends SIGTERM, waits up to 5s, falls back to SIGKILL.
+ */
+export async function stop(): Promise<{ stopped: boolean }> {
+  const config = await readConfig()
+  const { pid_file } = config.server
+
+  const pid = await readPid(pid_file)
+  if (pid === null) return { stopped: false }
+  if (!isAlive(pid)) {
+    await rm(pid_file, { force: true })
+    return { stopped: false }
+  }
+
+  process.kill(pid, 'SIGTERM')
+
+  // Poll for exit, up to 5s
+  const deadline = Date.now() + 5000
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 100))
+    if (!isAlive(pid)) {
+      await rm(pid_file, { force: true })
+      return { stopped: true }
+    }
+  }
+
+  // Force kill
+  try {
+    process.kill(pid, 'SIGKILL')
+  } catch {}
+  await rm(pid_file, { force: true })
+  return { stopped: true }
+}
+
+/**
+ * Get the current daemon status.
+ */
+export async function status(): Promise<DaemonStatus> {
+  const config = await readConfig()
+  const { mode, url, pid_file } = config.server
+
+  const pid = await readPid(pid_file)
+  const running = pid !== null && isAlive(pid)
+  const health = await healthCheck({ timeout: 2000, url })
+
+  return {
+    mode,
+    url,
+    running,
+    pid: running ? pid : null,
+    healthy: health.healthy,
+  }
+}
+
+/**
+ * Read the last N lines of the server log file.
+ */
+export async function readLogFile(options?: { lines?: number }): Promise<string> {
+  const config = await readConfig()
+  const lines = options?.lines ?? 50
+  try {
+    const content = await readFile(config.server.log_file, 'utf-8')
+    const allLines = content.trimEnd().split('\n')
+    return allLines.slice(-lines).join('\n')
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+      return ''
+    }
+    throw e
+  }
+}
+
+/**
+ * Ensure the server is running and healthy.
+ * Called by commands before making API calls.
+ */
+export async function ensureRunning(): Promise<void> {
+  const config = await readConfig()
+  const { mode, url } = config.server
+
+  // Check health first — fast path
+  const health = await healthCheck({ timeout: 2000, url })
+  if (health.healthy) return
+
+  if (mode === 'remote') {
+    throw createError(ErrorCode.SERVER_UNREACHABLE, {
+      params: [url],
+      hint: `Check the URL or run 'brainjar server remote <url>'.`,
+    })
+  }
+
+  // Local mode: auto-start
+  await cleanStalePid(config.server.pid_file)
+
+  try {
+    await start()
+  } catch (e) {
+    if (e instanceof IncurError) throw e
+    throw createError(ErrorCode.SERVER_START_FAILED, {
+      message: 'Failed to start brainjar server.',
+      hint: `Check ${config.server.log_file}`,
+    })
+  }
+
+  // Poll until healthy (200ms intervals, 10s timeout)
+  const deadline = Date.now() + 10_000
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 200))
+    const check = await healthCheck({ timeout: 2000, url })
+    if (check.healthy) return
+  }
+
+  throw createError(ErrorCode.SERVER_START_FAILED, {
+    message: 'Server started but failed health check after 10s.',
+    hint: `Check ${config.server.log_file}`,
+  })
+}

package/src/errors.ts

@@ -0,0 +1,172 @@
+import { Errors } from 'incur'
+
+const { IncurError } = Errors
+
+// ---------------------------------------------------------------------------
+// Error codes — single source of truth
+// ---------------------------------------------------------------------------
+
+export const ErrorCode = {
+  // HTTP-mapped
+  BAD_REQUEST: 'BAD_REQUEST',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  SERVER_ERROR: 'SERVER_ERROR',
+  SERVER_UNAVAILABLE: 'SERVER_UNAVAILABLE',
+  API_ERROR: 'API_ERROR',
+
+  // Domain: souls
+  SOUL_EXISTS: 'SOUL_EXISTS',
+  SOUL_NOT_FOUND: 'SOUL_NOT_FOUND',
+
+  // Domain: personas
+  PERSONA_EXISTS: 'PERSONA_EXISTS',
+  PERSONA_NOT_FOUND: 'PERSONA_NOT_FOUND',
+
+  // Domain: brains
+  BRAIN_EXISTS: 'BRAIN_EXISTS',
+  BRAIN_NOT_FOUND: 'BRAIN_NOT_FOUND',
+
+  // Domain: rules
+  RULE_EXISTS: 'RULE_EXISTS',
+  RULE_NOT_FOUND: 'RULE_NOT_FOUND',
+  RULES_NOT_FOUND: 'RULES_NOT_FOUND',
+
+  // Domain: state
+  NO_ACTIVE_SOUL: 'NO_ACTIVE_SOUL',
+  NO_ACTIVE_PERSONA: 'NO_ACTIVE_PERSONA',
+
+  // Packs
+  PACK_INVALID_VERSION: 'PACK_INVALID_VERSION',
+  PACK_DIR_EXISTS: 'PACK_DIR_EXISTS',
+  PACK_NO_MANIFEST: 'PACK_NO_MANIFEST',
+  PACK_CORRUPT_MANIFEST: 'PACK_CORRUPT_MANIFEST',
+  PACK_INVALID_MANIFEST: 'PACK_INVALID_MANIFEST',
+  PACK_MISSING_FILE: 'PACK_MISSING_FILE',
+  PACK_NOT_DIR: 'PACK_NOT_DIR',
+  PACK_NOT_FOUND: 'PACK_NOT_FOUND',
+
+  // Infra
+  TIMEOUT: 'TIMEOUT',
+  SERVER_UNREACHABLE: 'SERVER_UNREACHABLE',
+  BINARY_NOT_FOUND: 'BINARY_NOT_FOUND',
+  SERVER_START_FAILED: 'SERVER_START_FAILED',
+
+  // Validation
+  MUTUALLY_EXCLUSIVE: 'MUTUALLY_EXCLUSIVE',
+  MISSING_ARG: 'MISSING_ARG',
+  NO_OVERRIDES: 'NO_OVERRIDES',
+
+  // Other
+  INVALID_MODE: 'INVALID_MODE',
+  SHELL_ERROR: 'SHELL_ERROR',
+} as const
+
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode]
+
+// ---------------------------------------------------------------------------
+// Message templates — parameterized messages are functions, static are strings
+// Not every code needs an entry. Codes with context-dependent messages
+// (e.g. PACK_INVALID_MANIFEST) keep messages inline at the call site.
+// ---------------------------------------------------------------------------
+
+export const Messages: Partial<Record<ErrorCode, string | ((...args: string[]) => string)>> = {
+  // Souls
+  SOUL_EXISTS: (name: string) => `Soul "${name}" already exists.`,
+  SOUL_NOT_FOUND: (name: string) => `Soul "${name}" not found.`,
+
+  // Personas
+  PERSONA_EXISTS: (name: string) => `Persona "${name}" already exists.`,
+  PERSONA_NOT_FOUND: (name: string) => `Persona "${name}" not found.`,
+
+  // Brains
+  BRAIN_EXISTS: (name: string) => `Brain "${name}" already exists.`,
+  BRAIN_NOT_FOUND: (name: string) => `Brain "${name}" not found.`,
+
+  // Rules
+  RULE_EXISTS: (name: string) => `Rule "${name}" already exists.`,
+  RULE_NOT_FOUND: (name: string) => `Rule "${name}" not found.`,
+
+  // State
+  NO_ACTIVE_SOUL: 'Cannot save brain: no active soul.',
+  NO_ACTIVE_PERSONA: 'Cannot save brain: no active persona.',
+
+  // Packs
+  PACK_DIR_EXISTS: (dir: string) => `Pack directory "${dir}" already exists.`,
+  PACK_NO_MANIFEST: (dir: string) => `No pack.yaml found in "${dir}". Is this a brainjar pack?`,
+  PACK_NOT_DIR: (path: string) => `Pack path "${path}" is a file, not a directory. Packs are directories.`,
+  PACK_NOT_FOUND: (path: string) => `Pack path "${path}" does not exist.`,
+
+  // Infra
+  SERVER_UNREACHABLE: (url: string) => `Cannot reach server at ${url}`,
+}
+
+// ---------------------------------------------------------------------------
+// Hints — not every code has one
+// ---------------------------------------------------------------------------
+
+export const Hints: Partial<Record<ErrorCode, string | ((...args: string[]) => string)>> = {
+  // Domain: souls
+  SOUL_EXISTS: 'Pick a different name, or edit the existing one: `brainjar soul show <name>`',
+  SOUL_NOT_FOUND: 'List available souls: `brainjar soul list`',
+
+  // Domain: personas
+  PERSONA_EXISTS: 'Pick a different name, or edit the existing one: `brainjar persona show <name>`',
+  PERSONA_NOT_FOUND: 'List available personas: `brainjar persona list`',
+
+  // Domain: brains
+  BRAIN_EXISTS: 'Overwrite with --overwrite, or pick a different name.',
+  BRAIN_NOT_FOUND: 'List available brains: `brainjar brain list`',
+
+  // Domain: rules
+  RULE_EXISTS: 'Pick a different name, or edit the existing one: `brainjar rules show <name>`',
+  RULE_NOT_FOUND: 'List available rules: `brainjar rules list`',
+
+  // Domain: state
+  NO_ACTIVE_SOUL: 'Activate a soul first: `brainjar soul use <name>`',
+  NO_ACTIVE_PERSONA: 'Activate a persona first: `brainjar persona use <name>`',
+
+  // Packs
+  PACK_DIR_EXISTS: 'Remove the directory first, or use --out to write elsewhere.',
+  PACK_NO_MANIFEST: 'A valid pack needs a pack.yaml at its root.',
+
+  // Infra
+  BINARY_NOT_FOUND: 'Install the server: `brainjar init`',
+  SERVER_UNREACHABLE: 'Start the server: `brainjar server start`, or set a remote: `brainjar server remote <url>`',
+  SERVER_START_FAILED: 'Check server logs: `brainjar server logs`',
+  SERVER_UNAVAILABLE: 'Server is starting up. Retry in a moment, or check: `brainjar server status`',
+  UNAUTHORIZED: 'Verify server config: `brainjar server status`',
+  SERVER_ERROR: 'Check server logs: `brainjar server logs`',
+
+  // Validation
+  INVALID_MODE: 'Switch to local mode: `brainjar server local`',
+  NO_OVERRIDES: 'Pass --brain, --soul, --persona, --rules-add, or --rules-remove.',
+  MUTUALLY_EXCLUSIVE: 'Use one or the other, not both.',
+  MISSING_ARG: 'Run with --help to see usage.',
+}
+
+// ---------------------------------------------------------------------------
+// Factory — convenience for common patterns. Not mandatory.
+// ---------------------------------------------------------------------------
+
+export interface CreateErrorOptions {
+  message?: string
+  params?: string[]
+  hint?: string
+  retryable?: boolean
+  cause?: Error
+}
+
+export function createError(code: ErrorCode, options?: CreateErrorOptions): InstanceType<typeof IncurError> {
+  const template = Messages[code]
+  const message = options?.message
+    ?? (typeof template === 'function' ? template(...(options?.params ?? [])) : template)
+    ?? code
+  const hintTemplate = Hints[code]
+  const hint = options?.hint
+    ?? (typeof hintTemplate === 'function' ? (hintTemplate as (...args: string[]) => string)(...(options?.params ?? [])) : hintTemplate)
+
+  return new IncurError({ code, message, hint, retryable: options?.retryable, cause: options?.cause })
+}