@kelpie/server 0.1.0

package/src/lib/columns.ts

@@ -0,0 +1,170 @@
+import { sql } from 'drizzle-orm'
+import type { Column, SQL } from 'drizzle-orm'
+import { check, customType, text, timestamp } from 'drizzle-orm/pg-core'
+import type { PgColumn } from 'drizzle-orm/pg-core'
+
+/**
+ * Column conventions from `schema.md`, in one place so tables cannot drift.
+ *
+ * Primary keys are text `<prefix>_<ulid>` (see `lib/ids.ts`), not serials, so an
+ * id is meaningful on its own and safe to expose.
+ */
+
+/**
+ * Case-insensitive text, for emails and domains. Values are also normalised to
+ * lowercase on write; citext makes a stray uppercase comparison still match
+ * rather than silently creating a duplicate.
+ */
+export const citext = customType<{ data: string; driverData: string }>({
+  dataType: () => 'citext',
+})
+
+export function primaryId() {
+  return text('id').primaryKey()
+}
+
+/**
+ * A Postgres full-text vector, for the `search_vector` column every searchable
+ * table carries. Nothing selects it; it exists to be matched and ranked against.
+ */
+export const tsvector = customType<{ data: string; driverData: string }>({
+  dataType: () => 'tsvector',
+})
+
+/**
+ * The one text search configuration every vector and every query is built with.
+ *
+ * It has to be a literal rather than a setting: a generated column's expression
+ * must be immutable, and `to_tsvector(text)` without an explicit configuration
+ * reads `default_text_search_config` at run time, which makes it merely stable.
+ * A per-workspace language would therefore need its own column, not a parameter.
+ */
+export const SEARCH_CONFIGURATION = 'english'
+
+/**
+ * Where a field sits in a result's ranking. `ts_rank` weighs A heaviest.
+ *
+ * A is what the reader clicks: a name, a title, the body of a decision. B is the
+ * record's own prose. C is tags and other short arrays, which match usefully but
+ * should not outrank a name.
+ */
+export type SearchWeight = 'A' | 'B' | 'C'
+
+export interface SearchVectorPart {
+  readonly column: Column
+  readonly weight: SearchWeight
+  /**
+   * True for a `text[]` column. Arrays are flattened by
+   * `kelpie_text_array_to_string`, a wrapper that migration `0015` adds because
+   * `array_to_string` itself is stable rather than immutable and Postgres refuses
+   * a generated column built on it.
+   */
+  readonly array?: boolean
+}
+
+/**
+ * Every run of non-alphanumeric characters becomes a space before the text is
+ * tokenised.
+ *
+ * **The vector has to be split the same way the query is**, and the query splits
+ * on exactly this (`modules/search/query.ts`). Left alone, Postgres reads
+ * `ada@analytical.test` as one `email` token and `acme.com` as one `host` token,
+ * while a search for `analytical` arrives as the single word `analytical`. The two
+ * never meet, and an address is findable only by typing its opening characters.
+ *
+ * Immutable, which a generated column requires: `regexp_replace` with constant
+ * pattern and flags is marked `i` in `pg_proc`.
+ */
+const SPLIT_ON_PUNCTUATION = sql.raw("'[^[:alnum:]]+', ' ', 'g'")
+
+function searchVectorPart(part: SearchVectorPart): SQL {
+  const raw = part.array === true
+    ? sql`coalesce(kelpie_text_array_to_string(${part.column}), '')`
+    : sql`coalesce(${part.column}::text, '')`
+  const source = sql`regexp_replace(${raw}, ${SPLIT_ON_PUNCTUATION})`
+
+  return sql`setweight(to_tsvector(${sql.raw(`'${SEARCH_CONFIGURATION}'`)}, ${source}), ${sql.raw(`'${part.weight}'`)})`
+}
+
+/**
+ * The `search_vector` column: a stored, generated tsvector over the record's own
+ * text, indexed with GIN by the table that declares it.
+ *
+ * Generated rather than maintained by the service, so it cannot fall out of step
+ * with the row. A trigger or an application write would both leave a window where
+ * an updated record is unfindable, and an import that bypassed the service would
+ * leave one permanently.
+ *
+ * The declared return type is not decoration. Every part names a column of the
+ * table being declared, so an inferred one would send TypeScript around a cycle:
+ * the table's type needs this column's type, which would need the parts, which
+ * name the table. Naming the type up front cuts it, the same way Drizzle's own
+ * self-referencing examples annotate their generated expressions.
+ *
+ * @param parts Deferred for the same reason at run time. Reading them eagerly
+ *   would run before the table's own `const` is assigned.
+ */
+export function searchVector(parts: () => readonly SearchVectorPart[]): SearchVectorColumn {
+  return tsvector('search_vector').generatedAlwaysAs((): SQL =>
+    parts()
+      .map(searchVectorPart)
+      .reduce((left, right) => sql`${left} || ${right}`),
+  )
+}
+
+type SearchVectorColumn = ReturnType<ReturnType<typeof tsvector>['generatedAlwaysAs']>
+
+/**
+ * Timestamps are `Date` in TypeScript, never strings. Postgres renders its own
+ * string format (`2026-08-02 11:23:26.138+00`), which is not the ISO 8601 that
+ * `api.md` requires, so string mode would leak a non-conforming value straight
+ * onto the wire. Routes call `toISOString()` at the boundary.
+ */
+export function createdAt() {
+  return timestamp('created_at', { withTimezone: true, mode: 'date' }).notNull().defaultNow()
+}
+
+export function updatedAt() {
+  return timestamp('updated_at', { withTimezone: true, mode: 'date' }).notNull().defaultNow()
+}
+
+/** A timestamptz that carries a real domain meaning rather than row bookkeeping. */
+export function moment(name: string) {
+  return timestamp(name, { withTimezone: true, mode: 'date' })
+}
+
+/**
+ * A check constraint restricting a column to a fixed set, built from the same
+ * array the API validates against.
+ *
+ * `schema.md` stores fixed enums as text plus a check rather than as a Postgres
+ * enum, so that adding a value is a constraint swap instead of a type migration.
+ * The cost of that is two lists of the same values, one in the constraint and one
+ * at the boundary. Taking both from one array is what stops them drifting into a
+ * request the API accepts and the database rejects with a 500.
+ *
+ * @param values Literals from our own source, never request data. They are
+ *   inlined into DDL, so a quote in one would be a syntax error at boot.
+ */
+export function checkOneOf(name: string, column: PgColumn, values: readonly string[]) {
+  return check(name, oneOf(name, column, values))
+}
+
+/**
+ * The `column in (…)` half of such a constraint, for a column whose rule needs
+ * more than membership. A nullable enum is the case: `interview_stage` is either
+ * null or one of the stages, and only the second half comes from the array.
+ *
+ * @param constraintName Only for the error below, which fires at boot.
+ */
+export function oneOf(constraintName: string, column: Column, values: readonly string[]) {
+  const offending = values.find((value) => value.includes("'"))
+
+  if (offending !== undefined) {
+    throw new Error(
+      `Check constraint ${constraintName} cannot inline a value containing a quote: ${offending}`,
+    )
+  }
+
+  return sql`${column} in (${sql.raw(values.map((value) => `'${value}'`).join(', '))})`
+}

package/src/lib/config.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+
+import { emailConfigSchema } from './email.ts'
+import type { EmailConfig } from './email.ts'
+import { describeValidationIssue } from './errors.ts'
+
+/**
+ * The single place the service reads environment variables. Every other module
+ * receives configuration as an argument. Nothing defaults silently: a missing or
+ * malformed variable stops boot with the full list of problems.
+ */
+
+export type Environment = Readonly<Record<string, string | undefined>>
+
+export type RuntimeMode = 'development' | 'test' | 'production'
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+export interface KelpieConfig {
+  readonly runtimeMode: RuntimeMode
+  readonly port: number
+  readonly databaseUrl: string
+  readonly logLevel: LogLevel
+  /** Transactional mail only. Roadmap decision 4: configured, never hardcoded. */
+  readonly email: EmailConfig
+  /**
+   * Path to the deploy-time module override file (`lib/moduleConfig.ts`).
+   * Undefined is the ordinary case: no file, so each workspace's own module
+   * settings decide.
+   */
+  readonly moduleConfigPath: string | undefined
+}
+
+/** Thrown at boot when the environment cannot produce a valid configuration. */
+export class ConfigurationError extends Error {
+  readonly problems: readonly string[]
+
+  constructor(problems: readonly string[]) {
+    super(`Invalid environment configuration:\n${problems.map((problem) => `  - ${problem}`).join('\n')}`)
+    this.name = 'ConfigurationError'
+    this.problems = problems
+  }
+}
+
+function isPostgresUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value)
+    return protocol === 'postgres:' || protocol === 'postgresql:'
+  } catch {
+    return false
+  }
+}
+
+const environmentSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+  PORT: z.coerce.number().int().positive().max(65535),
+  DATABASE_URL: z
+    .string()
+    .refine(isPostgresUrl, { message: 'must be a postgres:// or postgresql:// connection string' }),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
+  KELPIE_MODULE_CONFIG_PATH: z.string().min(1).optional(),
+  ...emailConfigSchema.shape,
+})
+
+/**
+ * Parses an environment into a validated config.
+ *
+ * @param environment Raw variables, normally `process.env`.
+ * @throws ConfigurationError listing every invalid or missing variable.
+ */
+export function loadConfig(environment: Environment): KelpieConfig {
+  const result = environmentSchema.safeParse(environment)
+
+  if (!result.success) {
+    throw new ConfigurationError(result.error.issues.map(describeValidationIssue))
+  }
+
+  return {
+    runtimeMode: result.data.NODE_ENV,
+    port: result.data.PORT,
+    databaseUrl: result.data.DATABASE_URL,
+    logLevel: result.data.LOG_LEVEL,
+    email: { EMAIL_PROVIDER: result.data.EMAIL_PROVIDER, EMAIL_FROM: result.data.EMAIL_FROM },
+    moduleConfigPath: result.data.KELPIE_MODULE_CONFIG_PATH,
+  }
+}

package/src/lib/database.ts

@@ -0,0 +1,118 @@
+import { drizzle } from 'drizzle-orm/postgres-js'
+import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+
+import * as schema from '../schema/index.ts'
+import { describeThrown } from './errors.ts'
+import type { Logger } from './logger.ts'
+
+export type Database = PostgresJsDatabase<typeof schema>
+
+/**
+ * SQLSTATE raised by an explicit `ON DELETE RESTRICT`. Postgres uses this rather
+ * than 23503 when the constraint itself is what refused.
+ */
+export const RESTRICT_VIOLATION = '23001'
+
+/** SQLSTATE raised when a reference is violated without an explicit RESTRICT rule. */
+export const FOREIGN_KEY_VIOLATION = '23503'
+
+/** SQLSTATE for a unique violation, e.g. two people with one email in a workspace. */
+export const UNIQUE_VIOLATION = '23505'
+
+/**
+ * Reads a field off a driver error. Drizzle wraps driver errors in its own
+ * `Failed query` error, so the useful fields live on the cause rather than the
+ * top level.
+ */
+function driverErrorField(error: unknown, field: string): string | undefined {
+  const candidates: readonly unknown[] = [error, error instanceof Error ? error.cause : undefined]
+
+  for (const candidate of candidates) {
+    if (candidate instanceof Error && field in candidate) {
+      const value: unknown = (candidate as unknown as Record<string, unknown>)[field]
+
+      if (typeof value === 'string') {
+        return value
+      }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Digs the SQLSTATE out of a thrown value.
+ *
+ * @returns The five-character SQLSTATE, or undefined if this was not a database error.
+ */
+export function postgresErrorCode(error: unknown): string | undefined {
+  return driverErrorField(error, 'code')
+}
+
+/**
+ * The table that still references the row a delete tried to remove.
+ *
+ * Postgres names the *referencing* table, which is what `api.md` wants in the
+ * `details` of the 409: the caller needs to know what to detach, not which
+ * constraint object refused.
+ *
+ * @returns undefined when the error carries no table, which every caller must
+ *   tolerate: the 409 is still correct without it.
+ */
+export function referenceViolationTable(error: unknown): string | undefined {
+  return driverErrorField(error, 'table_name')
+}
+
+/**
+ * True when the database refused a write because another row still references the
+ * target. `api.md` renders this as `409` with the referencing types in `details`.
+ */
+export function isReferenceViolation(error: unknown): boolean {
+  const code = postgresErrorCode(error)
+
+  return code === RESTRICT_VIOLATION || code === FOREIGN_KEY_VIOLATION
+}
+
+/** Outcome of a connectivity check. Carries the reason instead of throwing. */
+export type DatabaseProbe = { readonly reachable: true } | { readonly reachable: false; readonly reason: string }
+
+export interface DatabaseConnection {
+  readonly db: Database
+  /** Round-trips a trivial query. Used by the health endpoint. */
+  readonly probe: () => Promise<DatabaseProbe>
+  readonly close: () => Promise<void>
+}
+
+/**
+ * Opens a lazy Postgres connection pool and wraps it in Drizzle.
+ *
+ * @param connectionString Validated by the config layer, never read from env here.
+ * @param logger Receives server notices. Without this the driver prints them to
+ *   stdout as loose objects, which breaks the JSON-lines log contract.
+ */
+export function connectDatabase(connectionString: string, logger: Logger): DatabaseConnection {
+  const client = postgres(connectionString, {
+    onnotice: (notice) => {
+      logger.debug('postgres notice', { code: notice.code, notice: notice.message })
+    },
+  })
+  const db = drizzle(client, { schema })
+
+  async function probe(): Promise<DatabaseProbe> {
+    try {
+      await client`select 1`
+      return { reachable: true }
+    } catch (error: unknown) {
+      // A probe reports unreachability; propagating would turn a health check
+      // into an outage. The reason is returned so the caller can log it.
+      return { reachable: false, reason: describeThrown(error) }
+    }
+  }
+
+  return {
+    db,
+    probe,
+    close: () => client.end(),
+  }
+}

package/src/lib/dates.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+
+/**
+ * The date-only wire format from `api.md`: `YYYY-MM-DD`.
+ *
+ * The shape check alone is not enough. `2026-02-30` matches the pattern, and
+ * Postgres refuses it at insert time, which reaches the caller as a 500 for what
+ * is a request error. Round-tripping the parsed date back to a string is what
+ * rejects a day that does not exist, as a 422.
+ */
+export const isoDateSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/u, 'Use YYYY-MM-DD')
+  .refine((value) => {
+    const parsed = new Date(`${value}T00:00:00Z`)
+
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value
+  }, 'That date does not exist')

package/src/lib/email.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+
+import type { Logger } from './logger.ts'
+
+/**
+ * The port Kelpie sends transactional mail through: invites, password resets,
+ * and account-change notifications, nothing else. Kelpie never sends outreach
+ * email.
+ *
+ * Roadmap decision 4: the provider is configured, never hardcoded. Core ships the
+ * port and the `log` provider. Real providers ship as modules, so the open-source
+ * assembly has no vendor account baked into it.
+ */
+
+export interface EmailMessage {
+  readonly to: string
+  readonly subject: string
+  readonly body: string
+}
+
+export interface EmailSender {
+  send(message: EmailMessage): Promise<void>
+}
+
+export const emailConfigSchema = z.object({
+  EMAIL_PROVIDER: z.enum(['log']),
+  EMAIL_FROM: z.string().min(1),
+})
+
+export type EmailConfig = z.infer<typeof emailConfigSchema>
+
+/**
+ * Writes the message to the log instead of sending it. For self-hosted
+ * development, where the reset link in the log is exactly what you want.
+ *
+ * This is a deliberate choice, not a fallback: `EMAIL_PROVIDER` has no default,
+ * so nobody reaches this provider without naming it.
+ */
+export function createLogEmailSender(logger: Logger, from: string): EmailSender {
+  return {
+    send(message) {
+      logger.info('email not sent: provider is "log"', {
+        from,
+        to: message.to,
+        subject: message.subject,
+        body: message.body,
+      })
+
+      return Promise.resolve()
+    },
+  }
+}
+
+/**
+ * Builds the configured sender.
+ *
+ * @throws Never. An unknown provider cannot reach here: the config schema is an
+ *   enum, so boot rejects it first.
+ */
+export function createEmailSender(config: EmailConfig, logger: Logger): EmailSender {
+  switch (config.EMAIL_PROVIDER) {
+    case 'log':
+      return createLogEmailSender(logger, config.EMAIL_FROM)
+  }
+}

package/src/lib/errors.ts

@@ -0,0 +1,156 @@
+/**
+ * The one error type services throw and routes render. Wire shape and status
+ * usage are fixed by `api.md`; this module is the only place that mapping lives.
+ */
+
+export type ErrorCode =
+  | 'bad_request'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'not_found'
+  | 'method_not_allowed'
+  | 'conflict'
+  | 'entitlement_required'
+  | 'validation_failed'
+  | 'rate_limited'
+  | 'internal_error'
+
+const statusByCode = {
+  bad_request: 400,
+  unauthorized: 401,
+  forbidden: 403,
+  not_found: 404,
+  // Extends the api.md status list, for the MCP transport. Its Streamable HTTP
+  // spec fixes 405 as the answer a server gives for the methods it does not
+  // offer, and a client reads it as "stop trying" rather than "try again".
+  method_not_allowed: 405,
+  conflict: 409,
+  // Extends the api.md status list: the plan does not include this, which is
+  // neither a role problem nor a conflict. 402 would imply Kelpie takes payment,
+  // which a self-hosted install does not.
+  entitlement_required: 403,
+  validation_failed: 422,
+  rate_limited: 429,
+  internal_error: 500,
+} as const satisfies Record<ErrorCode, number>
+
+export type ErrorStatus = (typeof statusByCode)[ErrorCode]
+
+export interface ErrorDetail {
+  readonly field: string
+  readonly message: string
+}
+
+export interface ErrorBody {
+  readonly error: {
+    readonly code: ErrorCode
+    readonly message: string
+    readonly details?: readonly ErrorDetail[]
+  }
+}
+
+export class AppError extends Error {
+  readonly code: ErrorCode
+  readonly status: ErrorStatus
+  readonly details: readonly ErrorDetail[] | undefined
+
+  constructor(code: ErrorCode, message: string, details?: readonly ErrorDetail[]) {
+    super(message)
+    this.name = 'AppError'
+    this.code = code
+    this.status = statusByCode[code]
+    this.details = details
+  }
+
+  static notFound(message = 'Not found'): AppError {
+    return new AppError('not_found', message)
+  }
+
+  static unauthorized(message = 'Missing or invalid credentials'): AppError {
+    return new AppError('unauthorized', message)
+  }
+
+  static validationFailed(message: string, details: readonly ErrorDetail[]): AppError {
+    return new AppError('validation_failed', message, details)
+  }
+
+  static conflict(message: string, details?: readonly ErrorDetail[]): AppError {
+    return new AppError('conflict', message, details)
+  }
+}
+
+/**
+ * Renders an `AppError` into the wire body from `api.md`. `details` is omitted
+ * rather than sent as null when the error carries none.
+ */
+export function toErrorBody(error: AppError): ErrorBody {
+  return {
+    error:
+      error.details === undefined
+        ? { code: error.code, message: error.message }
+        : { code: error.code, message: error.message, details: error.details },
+  }
+}
+
+/**
+ * The body sent for anything thrown that is not an `AppError`. The real cause is
+ * logged server-side; the client is told nothing about it.
+ */
+export function internalErrorBody(): ErrorBody {
+  return { error: { code: 'internal_error', message: 'Internal server error' } }
+}
+
+/** One problem reported by a schema parse, in the shape Zod produces. */
+export interface ValidationIssue {
+  readonly path: readonly PropertyKey[]
+  readonly message: string
+  /** Zod's issue code. Only `unrecognized_keys` is treated specially. */
+  readonly code?: string
+  /** The offending field names, when the issue is an unrecognised key. */
+  readonly keys?: readonly string[]
+}
+
+/** Renders a parse failure as `path: message`, or just the message at the root. */
+export function describeValidationIssue(issue: ValidationIssue): string {
+  const path = issue.path.map(String).join('.')
+
+  return path.length > 0 ? `${path}: ${issue.message}` : issue.message
+}
+
+/**
+ * Turns parse failures into the field-level `details` of a `422` response.
+ *
+ * An unrecognised key is reported against the key itself. Zod raises it at the
+ * object, so its path is empty, and `details` is where a client looks to find out
+ * which field it got wrong.
+ */
+export function toErrorDetails(issues: readonly ValidationIssue[]): readonly ErrorDetail[] {
+  return issues.flatMap((issue) => {
+    if (issue.code === 'unrecognized_keys' && issue.keys !== undefined) {
+      const prefix = issue.path.map(String).join('.')
+
+      return issue.keys.map((key) => ({
+        field: prefix.length > 0 ? `${prefix}.${key}` : key,
+        message: 'Unknown field',
+      }))
+    }
+
+    return [{ field: issue.path.map(String).join('.'), message: issue.message }]
+  })
+}
+
+/**
+ * Renders an unknown thrown value as one diagnostic line. Driver errors often
+ * carry an empty `message` and put the useful part in `name` or `code`, so all
+ * three are included.
+ */
+export function describeThrown(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return String(error)
+  }
+
+  const code = 'code' in error && typeof error.code === 'string' ? error.code : ''
+  const parts = [error.name, code, error.message].filter((part) => part.length > 0)
+
+  return parts.join(': ')
+}