@kelpie/server 0.1.0

package/src/testing/app.ts

@@ -0,0 +1,79 @@
+import type { Context, Hono } from 'hono'
+
+import { createApp } from '../app.ts'
+import type { AppBindings } from '../app.ts'
+import type { Actor } from '../lib/actor.ts'
+import type { Environment } from '../lib/config.ts'
+import type { DatabaseProbe } from '../lib/database.ts'
+import { createLogger } from '../lib/logger.ts'
+import type { KelpieModule } from '../runtime/module.ts'
+import type { ModuleContributions } from '../runtime/registry.ts'
+import type { EntitlementRegistry } from '../runtime/entitlements.ts'
+import { registerModules } from '../runtime/registry.ts'
+import { TEST_ENVIRONMENT } from './environment.ts'
+import { createTestServices } from './services.ts'
+import type { TestServices } from './services.ts'
+
+/**
+ * Assembles an app for tests. Unlike the real boot it defaults every dependency,
+ * because a test that has to spell out an environment it does not care about
+ * tests the harness instead of the code.
+ */
+
+export interface TestAppOptions {
+  readonly modules?: readonly KelpieModule[]
+  /** Defaults to `TEST_ENVIRONMENT`: enough for every core module to configure itself. */
+  readonly environment?: Environment
+  readonly probeDatabase?: () => Promise<DatabaseProbe>
+  readonly generateRequestId?: () => string
+  /** Defaults to fakes: a lazy unused database and a collecting email sender. */
+  readonly services?: TestServices
+  /** Inject one to grant or deny capabilities before core modules register. */
+  readonly entitlements?: EntitlementRegistry
+  /** A deploy-time module override, for a test exercising `runtime/moduleConfig.ts`. */
+  readonly moduleConfig?: Readonly<Record<string, boolean>>
+  /**
+   * Resolves the actor a REST request carries, for a test exercising module
+   * route gating. Omitted, as most tests want, gating is skipped and every
+   * route behaves as it did before module toggling existed.
+   */
+  readonly resolveActor?: (context: Context) => Promise<Actor>
+}
+
+export interface TestApp {
+  readonly app: Hono<AppBindings>
+  readonly services: TestServices
+  readonly contributions: ModuleContributions
+  /** Every log line the app emitted, newest last. */
+  readonly logLines: readonly string[]
+}
+
+const reachableDatabase = (): Promise<DatabaseProbe> => Promise.resolve({ reachable: true })
+
+export async function createTestApp(options: TestAppOptions = {}): Promise<TestApp> {
+  const logLines: string[] = []
+  const logger = createLogger('debug', (line) => logLines.push(line))
+
+  const services = options.services ?? createTestServices()
+  const contributions = await registerModules({
+    modules: options.modules ?? [],
+    environment: options.environment ?? TEST_ENVIRONMENT,
+    logger,
+    events: services.events,
+    ...(options.entitlements === undefined ? {} : { entitlements: options.entitlements }),
+    ...(options.moduleConfig === undefined ? {} : { moduleConfig: options.moduleConfig }),
+    ...(options.resolveActor === undefined ? {} : { resolveActor: options.resolveActor }),
+    services,
+  })
+
+  const app = createApp({
+    logger,
+    probeDatabase: options.probeDatabase ?? reachableDatabase,
+    contributions,
+    credentials: { db: services.db, now: services.now },
+    generateRequestId: options.generateRequestId ?? (() => 'req-test'),
+    createId: services.createId,
+  })
+
+  return { app, contributions, logLines, services }
+}

package/src/testing/client.ts

@@ -0,0 +1,118 @@
+import type { Hono } from 'hono'
+
+import type { AppBindings } from '../app.ts'
+
+/**
+ * An HTTP client for integration tests, plus the two setups almost every suite
+ * needs first: an account, and an account that owns a workspace.
+ *
+ * Requests go through `app.request`, so they run the real middleware chain,
+ * routing, and error rendering. Nothing here reaches around the API.
+ */
+
+export interface TestRequestOptions {
+  readonly body?: unknown
+  readonly cookie?: string | undefined
+  readonly bearer?: string | undefined
+}
+
+/** A signed-in owner of a fresh workspace: what most CRM tests start from. */
+export interface TestOwner {
+  readonly cookie: string
+  readonly workspaceId: string
+}
+
+export interface TestClient {
+  send(method: string, path: string, options?: TestRequestOptions): Promise<Response>
+  /** @returns The session cookie for the new account. */
+  signUp(email: string): Promise<string>
+  owner(email?: string, slug?: string): Promise<TestOwner>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** Reads a field a response is expected to carry, failing with the body when it does not. */
+export function readString(payload: unknown, key: string): string {
+  if (!isRecord(payload) || typeof payload[key] !== 'string') {
+    throw new Error(`Expected "${key}" on ${JSON.stringify(payload)}`)
+  }
+
+  return payload[key]
+}
+
+export function readRecord(payload: unknown): Record<string, unknown> {
+  if (!isRecord(payload)) {
+    throw new Error(`Expected an object, got ${JSON.stringify(payload)}`)
+  }
+
+  return payload
+}
+
+/** Reads the `data` array out of a `{ data, next_cursor }` envelope. */
+export function readList(payload: unknown): Record<string, unknown>[] {
+  if (!isRecord(payload) || !Array.isArray(payload.data)) {
+    throw new Error(`Expected a list envelope, got ${JSON.stringify(payload)}`)
+  }
+
+  return payload.data.filter(isRecord)
+}
+
+/** Reads `next_cursor`, which is a string or null and never absent. */
+export function readCursor(payload: unknown): string | null {
+  if (!isRecord(payload) || (payload.next_cursor !== null && typeof payload.next_cursor !== 'string')) {
+    throw new Error(`Expected "next_cursor" on ${JSON.stringify(payload)}`)
+  }
+
+  return payload.next_cursor
+}
+
+export function createTestClient(app: Hono<AppBindings>): TestClient {
+  function send(method: string, path: string, options: TestRequestOptions = {}): Promise<Response> {
+    return Promise.resolve(
+      app.request(path, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(options.cookie === undefined ? {} : { Cookie: options.cookie }),
+          ...(options.bearer === undefined ? {} : { Authorization: `Bearer ${options.bearer}` }),
+        },
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+      }),
+    )
+  }
+
+  async function signUp(email: string): Promise<string> {
+    const response = await send('POST', '/v1/auth/signup', {
+      body: { email, name: 'Someone', password: 'correct horse battery staple' },
+    })
+
+    if (response.status !== 201) {
+      throw new Error(`Signing up ${email} answered ${String(response.status)}`)
+    }
+
+    // Only the cookie's name=value matters to a later request; the attributes
+    // after the first semicolon are for a browser.
+    return (response.headers.get('Set-Cookie') ?? '').split(';')[0] ?? ''
+  }
+
+  return {
+    send,
+    signUp,
+
+    async owner(email = 'ada@example.com', slug = 'acme') {
+      const cookie = await signUp(email)
+      const created = await send('POST', '/v1/workspaces', {
+        body: { name: 'Acme', slug, timezone: 'Australia/Melbourne' },
+        cookie,
+      })
+
+      if (created.status !== 201) {
+        throw new Error(`Creating workspace ${slug} answered ${String(created.status)}`)
+      }
+
+      return { cookie, workspaceId: readString(await created.json(), 'id') }
+    },
+  }
+}

package/src/testing/database.ts

@@ -0,0 +1,106 @@
+import { sql } from 'drizzle-orm'
+import postgres from 'postgres'
+
+import type { Environment } from '../lib/config.ts'
+import { connectDatabase } from '../lib/database.ts'
+import type { DatabaseConnection } from '../lib/database.ts'
+import { createLogger } from '../lib/logger.ts'
+import { coreModules } from '../modules/core.ts'
+import { runMigrations } from '../runtime/migrate.ts'
+import { registerModules } from '../runtime/registry.ts'
+import { TEST_ENVIRONMENT } from './environment.ts'
+import { createTestServices } from './services.ts'
+
+/**
+ * A migrated database for integration tests.
+ *
+ * Tests connect to the same local Postgres the dev server uses, on a database
+ * named by `TEST_DATABASE_URL`. Migrations run once per process; between tests
+ * `truncateAll` empties the tables rather than re-migrating, which is an order of
+ * magnitude faster and just as isolated.
+ */
+
+const silentLogger = createLogger('error', () => undefined)
+
+export interface TestDatabase extends DatabaseConnection {
+  /** Empties every table. Cheaper than re-running migrations between tests. */
+  readonly truncateAll: () => Promise<void>
+}
+
+/**
+ * Reads the test database location. Integration tests are skipped rather than
+ * failed when it is absent, so `npm test` still works without Postgres running.
+ */
+export function testDatabaseUrl(environment: Environment): string | undefined {
+  return environment.TEST_DATABASE_URL
+}
+
+/**
+ * Creates the target database if it does not exist, by connecting to the server's
+ * maintenance database. Saves every contributor a manual `createdb` step.
+ */
+async function ensureDatabaseExists(connectionString: string): Promise<void> {
+  const url = new URL(connectionString)
+  const databaseName = decodeURIComponent(url.pathname.replace(/^\//u, ''))
+
+  if (databaseName.length === 0) {
+    throw new Error(`TEST_DATABASE_URL has no database name: ${connectionString}`)
+  }
+
+  const maintenanceUrl = new URL(connectionString)
+  maintenanceUrl.pathname = '/postgres'
+  const client = postgres(maintenanceUrl.toString(), { max: 1 })
+
+  try {
+    const existing = await client`select 1 from pg_database where datname = ${databaseName}`
+
+    if (existing.length === 0) {
+      // CREATE DATABASE cannot be parameterised or run inside a transaction.
+      // The name came from a connection string the developer set, not a request.
+      await client.unsafe(`create database "${databaseName.replace(/"/gu, '""')}"`)
+    }
+  } finally {
+    await client.end()
+  }
+}
+
+/**
+ * @param connectionString Where to connect. Callers pass `TEST_DATABASE_URL`;
+ *   this function never reads the environment itself.
+ */
+export async function connectTestDatabase(connectionString: string): Promise<TestDatabase> {
+  await ensureDatabaseExists(connectionString)
+
+  const connection = connectDatabase(connectionString, silentLogger)
+  const contributions = await registerModules({
+    modules: coreModules,
+    // Enough for core modules to configure themselves; no test reads it further.
+    environment: TEST_ENVIRONMENT,
+    logger: silentLogger,
+    services: createTestServices({ db: connection.db }),
+  })
+
+  await runMigrations(connection.db, contributions.schemas, silentLogger)
+
+  async function truncateAll(): Promise<void> {
+    // Names come from the catalog, not from user input, and every migrations
+    // table is excluded so truncation does not undo the migration record.
+    const rows = await connection.db.execute<{ table_name: string }>(sql`
+      select table_name
+      from information_schema.tables
+      where table_schema = 'public'
+        and table_type = 'BASE TABLE'
+        and table_name not like '\\_\\_drizzle\\_%'
+    `)
+
+    const names = [...rows].map((row) => `"${row.table_name}"`)
+
+    if (names.length === 0) {
+      return
+    }
+
+    await connection.db.execute(sql.raw(`truncate table ${names.join(', ')} restart identity cascade`))
+  }
+
+  return { ...connection, truncateAll }
+}

package/src/testing/environment.ts

@@ -0,0 +1,22 @@
+import type { Environment } from '../lib/config.ts'
+
+/**
+ * The environment a test app boots with.
+ *
+ * Core modules validate their own slice of configuration during `register`, so
+ * a suite that registers `coreModules` needs every variable they require. It
+ * lives here rather than in each suite because a module adding a variable
+ * should not mean editing twenty test files.
+ */
+
+/**
+ * A fixed key, so a sealed value is reproducible across runs. It protects
+ * nothing: every test database is truncated between cases, and no production
+ * secret is ever sealed with it.
+ */
+export const TEST_SECRET_ENCRYPTION_KEY = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA='
+
+export const TEST_ENVIRONMENT: Environment = {
+  NODE_ENV: 'test',
+  SECRET_ENCRYPTION_KEY: TEST_SECRET_ENCRYPTION_KEY,
+}

package/src/testing/fixtures.ts

@@ -0,0 +1,70 @@
+import type { ApiKeyActor } from '../lib/actor.ts'
+import type { Database } from '../lib/database.ts'
+import { createIdFactory } from '../lib/ids.ts'
+import { users } from '../modules/auth/schema.ts'
+import { workspaceMembers, workspaces } from '../modules/workspace/schema.ts'
+
+/**
+ * The minimum a workspace-scoped test needs: a user, a workspace, and an owner
+ * membership linking them. Everything else in the domain hangs off these.
+ */
+
+const createId = createIdFactory()
+
+export interface WorkspaceFixture {
+  readonly workspaceId: string
+  readonly userId: string
+  readonly memberId: string
+}
+
+/**
+ * @param db Target database, already migrated.
+ * @param slug Workspace slug. Unique per workspace, so tests that create two
+ *   workspaces must pass different values.
+ */
+export async function insertWorkspaceFixture(db: Database, slug = 'acme'): Promise<WorkspaceFixture> {
+  const userId = createId('user')
+  const workspaceId = createId('workspace')
+  const memberId = createId('teamMember')
+
+  await db.insert(users).values({
+    id: userId,
+    email: `${slug}-owner@example.com`,
+    name: 'Ada Lovelace',
+    passwordHash: 'not-a-real-hash',
+  })
+
+  await db.insert(workspaces).values({
+    id: workspaceId,
+    name: 'Acme',
+    slug,
+    timezone: 'Australia/Melbourne',
+  })
+
+  await db.insert(workspaceMembers).values({
+    id: memberId,
+    workspaceId,
+    userId,
+    role: 'owner',
+  })
+
+  return { workspaceId, userId, memberId }
+}
+
+/**
+ * A workspace key's actor, for a test that calls a service or an MCP tool
+ * directly rather than over HTTP.
+ *
+ * A workspace key rather than a session, because that is what reaches the MCP
+ * endpoint: it takes bearer keys only.
+ */
+export function workspaceKeyActor(workspaceId: string): ApiKeyActor {
+  return {
+    kind: 'api_key',
+    apiKeyId: createId('apiKey'),
+    userId: null,
+    workspaceId,
+    role: 'admin',
+    memberId: null,
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,13 @@
+export { createTestApp } from './app.ts'
+export type { TestApp, TestAppOptions } from './app.ts'
+
+export { TEST_ENVIRONMENT, TEST_SECRET_ENCRYPTION_KEY } from './environment.ts'
+
+export { connectTestDatabase, testDatabaseUrl } from './database.ts'
+export type { TestDatabase } from './database.ts'
+
+export { insertWorkspaceFixture, workspaceKeyActor } from './fixtures.ts'
+export type { WorkspaceFixture } from './fixtures.ts'
+
+export { createTestClient, readCursor, readList, readRecord, readString } from './client.ts'
+export type { TestClient, TestOwner, TestRequestOptions } from './client.ts'

package/src/testing/services.ts

@@ -0,0 +1,67 @@
+import { connectDatabase } from '../lib/database.ts'
+import type { Database } from '../lib/database.ts'
+import type { EmailMessage, EmailSender } from '../lib/email.ts'
+import { createIdFactory } from '../lib/ids.ts'
+import type { IdFactory } from '../lib/ids.ts'
+import { createLogger } from '../lib/logger.ts'
+import { createEventBus } from '../runtime/events.ts'
+import type { EventBus } from '../runtime/events.ts'
+import type { ModuleServices } from '../runtime/module.ts'
+import { createTransactionScope } from '../runtime/transaction.ts'
+
+/**
+ * The collaborators a module needs, wired for tests.
+ *
+ * Without a database the connection is still real, just never opened: postgres.js
+ * connects lazily. A test that queries by accident fails on connect rather than
+ * against a stub that quietly agrees with it.
+ */
+
+/** Never queried. A unit test that reaches the database fails here, loudly. */
+const UNUSED_DATABASE_URL = 'postgres://unused:unused@127.0.0.1:1/unused'
+
+export interface TestServicesOptions {
+  readonly db?: Database
+  readonly now?: () => Date
+  readonly createId?: IdFactory
+  readonly events?: EventBus
+}
+
+export interface TestServices extends ModuleServices {
+  /** Everything the email port was asked to send, in order. */
+  readonly sentEmails: readonly EmailMessage[]
+  readonly events: EventBus
+}
+
+/** Collects messages instead of sending them, so a test can read the reset link. */
+function createCollectingEmailSender(): { sender: EmailSender; sent: EmailMessage[] } {
+  const sent: EmailMessage[] = []
+
+  return {
+    sent,
+    sender: {
+      send(message) {
+        sent.push(message)
+
+        return Promise.resolve()
+      },
+    },
+  }
+}
+
+export function createTestServices(options: TestServicesOptions = {}): TestServices {
+  const logger = createLogger('error', () => undefined)
+  const db = options.db ?? connectDatabase(UNUSED_DATABASE_URL, logger).db
+  const events = options.events ?? createEventBus(logger)
+  const { sender, sent } = createCollectingEmailSender()
+
+  return {
+    db,
+    transaction: createTransactionScope({ db, bus: events, logger }),
+    email: sender,
+    createId: options.createId ?? createIdFactory(),
+    now: options.now ?? ((): Date => new Date()),
+    sentEmails: sent,
+    events,
+  }
+}