@kelpie/server 0.1.0

package/src/runtime/module.ts

@@ -0,0 +1,147 @@
+import type { Hono } from 'hono'
+import type { ZodType } from 'zod'
+
+import type { Actor } from '../lib/actor.ts'
+import type { Database } from '../lib/database.ts'
+import type { EmailSender } from '../lib/email.ts'
+import type { IdFactory } from '../lib/ids.ts'
+import type { Logger } from '../lib/logger.ts'
+import type { EntitlementRegistry } from './entitlements.ts'
+import type { EventBus } from './events.ts'
+import type { TransactionScope } from './transaction.ts'
+
+/**
+ * The module contract from `modules.md`. Core features register through this
+ * same runtime, so anything core can do, a module can do.
+ *
+ * Composition is build-time: an assembly lists its modules in `kelpie.config.ts`
+ * and the runtime registers them. There is no runtime plugin loading.
+ */
+
+/** A module's Drizzle tables plus the directory holding its migrations. */
+export interface SchemaContribution {
+  readonly moduleId: string
+  /** The module's schema namespace: table, relation, and enum exports. */
+  readonly tables: Readonly<Record<string, unknown>>
+  readonly migrationsDir: string
+}
+
+/**
+ * A tool as a module declares it. The input schema is the same one the matching
+ * REST route validates with, so the two surfaces cannot drift.
+ *
+ * `invoke` receives the caller for the same reason a route handler resolves one:
+ * every service call is authorized against an actor and scoped to its workspace.
+ * The MCP endpoint resolves it once per request from the bearer key and hands it
+ * down, so a tool never reads identity from anywhere but its own arguments.
+ */
+export interface McpToolDefinition<Input> {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: ZodType<Input>
+  readonly invoke: (input: Input, actor: Actor) => Promise<unknown>
+}
+
+/**
+ * A tool as the registry holds it. Registration erases the input type behind a
+ * parse, so every call is validated before the tool body sees it.
+ */
+export interface McpTool {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: ZodType
+  readonly invoke: (rawInput: unknown, actor: Actor) => Promise<unknown>
+}
+
+export interface McpToolRegistry {
+  tool<Input>(definition: McpToolDefinition<Input>): void
+}
+
+/**
+ * What a module gets to build with, beyond its own contributions.
+ *
+ * `modules.md` does not list these. A module that contributes tables has no way
+ * to query them without a handle, and every write needs the transaction scope so
+ * its events publish after commit rather than during. Recorded here as the
+ * builder decision the spec left open.
+ */
+export interface ModuleServices {
+  readonly db: Database
+  /** Runs work in one transaction and publishes its events after commit. */
+  readonly transaction: TransactionScope
+  /** Transactional mail only: invites and password resets. */
+  readonly email: EmailSender
+  /** Generates `<prefix>_<ulid>` ids. Injected so tests can pin them. */
+  readonly createId: IdFactory
+  /** The current time, injected so expiry logic is testable. */
+  readonly now: () => Date
+}
+
+export interface ModuleContext extends ModuleServices {
+  /** Registers routes. They mount under `/v1` and are public API like any other. */
+  routes(mount: (router: Hono) => void): void
+  /**
+   * Registers routes that mount under `/v1/public`, take no credentials, and
+   * answer cross-origin requests from any site.
+   *
+   * A second method rather than an argument to `routes`, because the auth
+   * boundary is then visible at the call site: a reader of a module's `register`
+   * can see which of its endpoints anyone on the internet may call.
+   *
+   * A handler here has no `Actor` and therefore no workspace. It must resolve one
+   * from something in the request that identifies it — a form's `publicKey` — and
+   * scope every query to that. There is no other way in.
+   */
+  publicRoutes(mount: (router: Hono) => void): void
+  schema(tables: Readonly<Record<string, unknown>>, migrationsDir: string): void
+  readonly mcp: McpToolRegistry
+  /**
+   * Subscribe to domain events. Handlers run after the emitting transaction
+   * commits, and must be idempotent.
+   */
+  readonly events: EventBus
+  /**
+   * Declare capabilities and check grants. Every check is granted and unlimited
+   * until a module registers a provider.
+   */
+  readonly entitlements: EntitlementRegistry
+  /** Validates this module's slice of the environment. Fails boot when invalid. */
+  config<T>(schema: ZodType<T>): T
+  readonly log: Logger
+  /**
+   * Every module in the assembly, id and `structural` flag only. The workspace
+   * module's settings screen is the one reader today: it needs the toggleable
+   * id list and cannot import `modules/core.ts` itself without a cycle, since
+   * that file is what constructs the workspace module in the first place.
+   */
+  readonly moduleCatalog: readonly ModuleCatalogEntry[]
+  /**
+   * The deploy-time module override (`lib/moduleConfig.ts`), unparsed into
+   * grants. The workspace module reads this to answer whether a module's value
+   * is locked, which `EntitlementRegistry.check`'s single merged answer cannot
+   * tell a caller on its own.
+   */
+  readonly moduleConfig: Readonly<Record<string, boolean>> | undefined
+}
+
+export interface ModuleCatalogEntry {
+  readonly id: string
+  readonly structural: boolean
+}
+
+export interface KelpieModule {
+  readonly id: string
+  /** Ids of modules that must register first. Missing ones fail boot. */
+  readonly requires?: readonly string[]
+  /**
+   * Marks a module as always enabled: no `module.<id>` capability is declared for
+   * it, its routes and MCP tools are never gated, and a deploy-time module config
+   * file or a workspace's own settings may not name it. True for the modules the
+   * rest of the app cannot function without.
+   *
+   * Absent (or false) means toggleable, which is the default a new module gets
+   * without its author having to opt in.
+   */
+  readonly structural?: boolean
+  register(context: ModuleContext): Promise<void>
+}

package/src/runtime/moduleConfig.ts

@@ -0,0 +1,68 @@
+import type { GrantProvider } from './entitlements.ts'
+import type { KelpieModule } from './module.ts'
+import { ModuleBootError } from './order.ts'
+
+/**
+ * The capability namespace `registry.ts` declares one flag under per
+ * non-structural module: `module.<id>`. Kept here, alongside the two things
+ * that read and write it, so the prefix has one owner.
+ */
+const MODULE_CAPABILITY_PREFIX = 'module.'
+
+export function moduleCapabilityName(moduleId: string): string {
+  return `${MODULE_CAPABILITY_PREFIX}${moduleId}`
+}
+
+/** The inverse of `moduleCapabilityName`, for a provider deciding whether a capability is its concern. */
+export function parseModuleCapability(capabilityName: string): string | undefined {
+  return capabilityName.startsWith(MODULE_CAPABILITY_PREFIX)
+    ? capabilityName.slice(MODULE_CAPABILITY_PREFIX.length)
+    : undefined
+}
+
+/**
+ * Validates a deploy-time module override (`lib/moduleConfig.ts`) against the
+ * assembled module list, the same way an unmet `requires` fails boot.
+ *
+ * @throws ModuleBootError listing every id that does not exist or names a
+ *   structural module, which cannot be locked because it cannot be disabled.
+ */
+export function validateModuleConfig(
+  overrides: Readonly<Record<string, boolean>>,
+  modules: readonly KelpieModule[],
+): void {
+  const byId = new Map(modules.map((module) => [module.id, module]))
+  const problems: string[] = []
+
+  for (const moduleId of Object.keys(overrides)) {
+    const module = byId.get(moduleId)
+
+    if (module === undefined) {
+      problems.push(`module config names "${moduleId}", which is not in the module list`)
+      continue
+    }
+
+    if (module.structural === true) {
+      problems.push(`module config names "${moduleId}", which is structural and cannot be disabled`)
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new ModuleBootError(problems)
+  }
+}
+
+/**
+ * Answers every `module.<id>` capability the deploy-time file has an opinion
+ * on. Registered ahead of any module's own provider (`registry.ts`), so a
+ * locked value wins over a workspace's own setting: `EntitlementRegistry.check`
+ * asks providers in registration order and stops at the first answer.
+ */
+export function createModuleConfigProvider(overrides: Readonly<Record<string, boolean>>): GrantProvider {
+  return (_workspaceId, capability) => {
+    const moduleId = parseModuleCapability(capability.name)
+    const enabled = moduleId === undefined ? undefined : overrides[moduleId]
+
+    return Promise.resolve(enabled === undefined ? undefined : { kind: 'flag', granted: enabled })
+  }
+}

package/src/runtime/order.ts

@@ -0,0 +1,90 @@
+import type { KelpieModule } from './module.ts'
+
+/**
+ * Boot failed while validating or registering modules. Carries every problem
+ * found, so a misconfigured assembly reports all of them at once rather than
+ * one per run.
+ */
+export class ModuleBootError extends Error {
+  readonly problems: readonly string[]
+
+  constructor(problems: readonly string[], options?: ErrorOptions) {
+    super(`Module boot failed:\n${problems.map((problem) => `  - ${problem}`).join('\n')}`, options)
+    this.name = 'ModuleBootError'
+    this.problems = problems
+  }
+}
+
+function findStructuralProblems(modules: readonly KelpieModule[], byId: ReadonlyMap<string, KelpieModule>): string[] {
+  const problems: string[] = []
+  const seen = new Set<string>()
+
+  for (const module of modules) {
+    if (seen.has(module.id)) {
+      problems.push(`duplicate module id "${module.id}"`)
+    }
+    seen.add(module.id)
+  }
+
+  for (const module of modules) {
+    for (const required of module.requires ?? []) {
+      if (!byId.has(required)) {
+        problems.push(`module "${module.id}" requires "${required}", which is not in the module list`)
+      }
+    }
+  }
+
+  return problems
+}
+
+/**
+ * Sorts modules so each one registers after everything it `requires`.
+ *
+ * Independent modules keep their declared order, which is how `architecture.md`
+ * pins the core module sequence. Nothing else about runtime behaviour may depend
+ * on ordering.
+ *
+ * @throws ModuleBootError on duplicate ids, unmet `requires`, or a dependency cycle.
+ */
+export function orderModules(modules: readonly KelpieModule[]): readonly KelpieModule[] {
+  const byId = new Map(modules.map((module) => [module.id, module]))
+  const problems = findStructuralProblems(modules, byId)
+
+  if (problems.length > 0) {
+    throw new ModuleBootError(problems)
+  }
+
+  const ordered: KelpieModule[] = []
+  const progress = new Map<string, 'visiting' | 'done'>()
+
+  function visit(module: KelpieModule, trail: readonly string[]): void {
+    const state = progress.get(module.id)
+
+    if (state === 'done') {
+      return
+    }
+
+    if (state === 'visiting') {
+      throw new ModuleBootError([`module dependency cycle: ${[...trail, module.id].join(' -> ')}`])
+    }
+
+    progress.set(module.id, 'visiting')
+
+    for (const required of module.requires ?? []) {
+      const dependency = byId.get(required)
+
+      if (dependency !== undefined) {
+        visit(dependency, [...trail, module.id])
+      }
+    }
+
+    progress.set(module.id, 'done')
+    ordered.push(module)
+  }
+
+  for (const module of modules) {
+    visit(module, [])
+  }
+
+  return ordered
+}

package/src/runtime/registry.ts

@@ -0,0 +1,263 @@
+import { Hono } from 'hono'
+import type { Context } from 'hono'
+
+import type { Actor } from '../lib/actor.ts'
+import { requireWorkspaceId } from '../lib/actor.ts'
+import type { Environment } from '../lib/config.ts'
+import { AppError, describeThrown, describeValidationIssue, toErrorDetails } from '../lib/errors.ts'
+import type { Logger } from '../lib/logger.ts'
+import { createEntitlementRegistry, requireCapability } from './entitlements.ts'
+import type { EntitlementRegistry } from './entitlements.ts'
+import { createEventBus } from './events.ts'
+import type { EventBus } from './events.ts'
+import type {
+  KelpieModule,
+  McpTool,
+  ModuleCatalogEntry,
+  ModuleContext,
+  ModuleServices,
+  SchemaContribution,
+} from './module.ts'
+import { createModuleConfigProvider, moduleCapabilityName, validateModuleConfig } from './moduleConfig.ts'
+import { ModuleBootError, orderModules } from './order.ts'
+
+/**
+ * Everything the modules contributed during the registration pass. The app mounts
+ * the routers; the migration pipeline and the MCP endpoint consume the rest as
+ * those land.
+ */
+export interface ModuleContributions {
+  readonly routers: readonly ModuleRouter[]
+  /** Routers for `/v1/public`: no credentials, CORS open. `architecture.md` boot step 5. */
+  readonly publicRouters: readonly ModuleRouter[]
+  readonly schemas: readonly SchemaContribution[]
+  readonly mcpTools: readonly McpTool[]
+  /** The bus every module subscribed to. Services publish through it after commit. */
+  readonly events: EventBus
+  /** Everything the modules declared, and any provider they registered. */
+  readonly entitlements: EntitlementRegistry
+}
+
+export interface ModuleRouter {
+  readonly moduleId: string
+  readonly router: Hono
+}
+
+export interface ModuleRuntimeOptions {
+  readonly modules: readonly KelpieModule[]
+  /** Raw variables. Each module validates the slice it needs via `context.config`. */
+  readonly environment: Environment
+  readonly logger: Logger
+  /** Injected so a test can watch what core modules subscribe to. Defaults to a fresh bus. */
+  readonly events?: EventBus
+  /** Injected so a test can grant or deny before core modules register. */
+  readonly entitlements?: EntitlementRegistry
+  /** The database, transaction scope, and collaborators every module builds on. */
+  readonly services: ModuleServices
+  /**
+   * The deploy-time module override (`lib/moduleConfig.ts`), parsed. A locked
+   * module id wins over whatever a workspace's own settings say.
+   */
+  readonly moduleConfig?: Readonly<Record<string, boolean>>
+  /**
+   * Resolves the caller of a REST request, the same way every route already
+   * does (`modules/auth/credentials.ts`), so a non-structural module's router
+   * can be gated by `module.<id>` before any of its own routes run.
+   *
+   * Optional, and not part of `ModuleServices`: `runtime/` must not import a
+   * feature module, so this arrives as a function rather than a dependency on
+   * auth directly. Omitted, REST gating is skipped entirely, which is what
+   * every test that does not exercise module toggling wants without having to
+   * say so.
+   */
+  readonly resolveActor?: (context: Context) => Promise<Actor>
+}
+
+/** Contributions accumulate here, one mutable set per registration pass. */
+interface Accumulator {
+  readonly routers: ModuleRouter[]
+  readonly publicRouters: ModuleRouter[]
+  readonly schemas: SchemaContribution[]
+  readonly mcpTools: McpTool[]
+}
+
+function createModuleContext(
+  module: KelpieModule,
+  accumulator: Accumulator,
+  options: ModuleRuntimeOptions,
+  events: EventBus,
+  entitlements: EntitlementRegistry,
+  moduleCatalog: readonly ModuleCatalogEntry[],
+): ModuleContext {
+  return {
+    ...options.services,
+
+    routes(mount) {
+      const router = new Hono()
+
+      // Gate first, so it runs before anything `mount` adds: Hono composes a
+      // path's handlers in the order they were registered on this router,
+      // middleware included, and registering after the routes it should guard
+      // would run it too late to block them.
+      if (module.structural !== true && options.resolveActor !== undefined) {
+        const { resolveActor } = options
+
+        router.use('*', async (context, next) => {
+          const actor = await resolveActor(context)
+
+          await requireCapability(entitlements, requireWorkspaceId(actor), moduleCapabilityName(module.id))
+          await next()
+        })
+      }
+
+      mount(router)
+      accumulator.routers.push({ moduleId: module.id, router })
+    },
+
+    publicRoutes(mount) {
+      const router = new Hono()
+      mount(router)
+      accumulator.publicRouters.push({ moduleId: module.id, router })
+    },
+
+    schema(tables, migrationsDir) {
+      accumulator.schemas.push({ moduleId: module.id, tables, migrationsDir })
+    },
+
+    mcp: {
+      tool(definition) {
+        if (accumulator.mcpTools.some((existing) => existing.name === definition.name)) {
+          throw new ModuleBootError([`module "${module.id}" declares MCP tool "${definition.name}" twice`])
+        }
+
+        accumulator.mcpTools.push({
+          name: definition.name,
+          description: definition.description,
+          inputSchema: definition.inputSchema,
+          // Parsing here is what keeps MCP and REST from drifting: both surfaces
+          // validate with the module's schema and fail with the same api.md error.
+          invoke: async (rawInput, actor) => {
+            const parsed = definition.inputSchema.safeParse(rawInput)
+
+            if (!parsed.success) {
+              throw AppError.validationFailed(
+                `Invalid arguments for tool "${definition.name}"`,
+                toErrorDetails(parsed.error.issues),
+              )
+            }
+
+            // The MCP endpoint already resolved `actor` once, from the bearer
+            // key, before dispatch reached here (`modules/mcp/router.ts`), so
+            // gating needs no resolution step of its own the way the REST
+            // gate above does.
+            if (module.structural !== true) {
+              await requireCapability(entitlements, requireWorkspaceId(actor), moduleCapabilityName(module.id))
+            }
+
+            return definition.invoke(parsed.data, actor)
+          },
+        })
+      },
+    },
+
+    config(schema) {
+      const result = schema.safeParse(options.environment)
+
+      if (!result.success) {
+        throw new ModuleBootError(
+          result.error.issues.map((issue) => `module "${module.id}" config ${describeValidationIssue(issue)}`),
+        )
+      }
+
+      return result.data
+    },
+
+    events,
+    entitlements,
+
+    log: options.logger.child({ module: module.id }),
+
+    moduleCatalog,
+    moduleConfig: options.moduleConfig,
+  }
+}
+
+/**
+ * Runs the registration pass: validate the module list, then call each module's
+ * `register` once, in dependency order.
+ *
+ * @returns The accumulated contributions.
+ * @throws ModuleBootError when the list is invalid or a module fails to register.
+ */
+export async function registerModules(options: ModuleRuntimeOptions): Promise<ModuleContributions> {
+  const ordered = orderModules(options.modules)
+
+  if (options.moduleConfig !== undefined) {
+    validateModuleConfig(options.moduleConfig, options.modules)
+  }
+
+  const events = options.events ?? createEventBus(options.logger)
+  const entitlements = options.entitlements ?? createEntitlementRegistry()
+  const accumulator: Accumulator = {
+    routers: [],
+    publicRouters: [],
+    schemas: [],
+    mcpTools: [],
+  }
+  const moduleCatalog: readonly ModuleCatalogEntry[] = ordered.map((module) => ({
+    id: module.id,
+    structural: module.structural === true,
+  }))
+
+  // Declared once, centrally, rather than by each module's own `register`: a
+  // module author does nothing to become toggleable, which is the point of
+  // `structural` defaulting to false.
+  for (const module of ordered) {
+    if (module.structural !== true) {
+      entitlements.declare({
+        name: moduleCapabilityName(module.id),
+        kind: 'flag',
+        description: `Whether the "${module.id}" module is enabled for a workspace.`,
+      })
+    }
+  }
+
+  // Ahead of the registration loop, so it precedes any provider a module adds
+  // during its own `register` and therefore wins `EntitlementRegistry.check`'s
+  // first-answer-wins walk over providers.
+  if (options.moduleConfig !== undefined) {
+    entitlements.provide(createModuleConfigProvider(options.moduleConfig))
+  }
+
+  for (const module of ordered) {
+    const context = createModuleContext(module, accumulator, options, events, entitlements, moduleCatalog)
+
+    try {
+      await module.register(context)
+    } catch (error: unknown) {
+      if (error instanceof ModuleBootError) {
+        throw error
+      }
+
+      throw new ModuleBootError([`module "${module.id}" failed to register: ${describeThrown(error)}`], {
+        cause: error,
+      })
+    }
+
+    context.log.debug('module registered')
+  }
+
+  options.logger.info('modules registered', {
+    count: ordered.length,
+    ids: ordered.map((module) => module.id),
+  })
+
+  return {
+    routers: accumulator.routers,
+    publicRouters: accumulator.publicRouters,
+    schemas: accumulator.schemas,
+    mcpTools: accumulator.mcpTools,
+    events,
+    entitlements,
+  }
+}

package/src/runtime/transaction.ts

@@ -0,0 +1,80 @@
+import type { Database } from '../lib/database.ts'
+import type { Logger } from '../lib/logger.ts'
+import type { DomainEventName, DomainEvents, EventBus } from './events.ts'
+
+/**
+ * One service call, one transaction, per `architecture.md`.
+ *
+ * Events emitted inside the work are buffered and published only after the
+ * transaction commits. A transaction that rolls back publishes nothing, so no
+ * consumer ever sees a record that does not exist.
+ */
+
+/** The transaction handle Drizzle passes to the work. Repositories join it. */
+export type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0]
+
+/**
+ * What a repository function runs against: the pool for a single read, or an open
+ * transaction when a service is composing several writes.
+ */
+export type Queryable = Database | Transaction
+
+/** Collects events during the transaction. Nothing leaves until commit. */
+export interface BufferedEvents {
+  emit<Name extends DomainEventName>(name: Name, payload: DomainEvents[Name]): void
+}
+
+export interface TransactionContext {
+  readonly tx: Transaction
+  readonly events: BufferedEvents
+}
+
+/** Runs `work` in one transaction and publishes its events after commit. */
+export type TransactionScope = <Result>(
+  work: (context: TransactionContext) => Promise<Result>,
+) => Promise<Result>
+
+/**
+ * A buffered event keeps its publication as a closure. The name and payload were
+ * correlated at the `emit` call site; storing them as a pair would lose that and
+ * force a cast at publication.
+ */
+interface BufferedEvent {
+  readonly name: DomainEventName
+  readonly publish: () => Promise<void>
+}
+
+export interface TransactionScopeDependencies {
+  readonly db: Database
+  readonly bus: EventBus
+  readonly logger: Logger
+}
+
+export function createTransactionScope(dependencies: TransactionScopeDependencies): TransactionScope {
+  return async function runInTransaction(work) {
+    const buffered: BufferedEvent[] = []
+
+    const result = await dependencies.db.transaction((tx) =>
+      work({
+        tx,
+        events: {
+          emit(name, payload) {
+            buffered.push({ name, publish: () => dependencies.bus.publish(name, payload) })
+          },
+        },
+      }),
+    )
+
+    // Past this line the transaction has committed. Publishing is deliberately
+    // not awaited: the webhooks engine is a consumer, and an outbound HTTP
+    // delivery must not sit inside the request that triggered it. Tests and
+    // graceful shutdown wait via `bus.drain()`.
+    for (const event of buffered) {
+      void event.publish().catch((error: unknown) => {
+        dependencies.logger.error('event publication failed', { event: event.name, error })
+      })
+    }
+
+    return result
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Every core table, in one namespace.
+ *
+ * Tables are defined in the module that owns them; this barrel is what Drizzle
+ * and drizzle-kit read. Modules outside core bring their own schema and their own
+ * migrations directory through `context.schema()`.
+ */
+
+export * from '../modules/auth/schema.ts'
+export * from '../modules/workspace/schema.ts'
+export * from '../modules/api-keys/schema.ts'
+export * from '../modules/people/schema.ts'
+export * from '../modules/companies/schema.ts'
+export * from '../modules/positions/schema.ts'
+export * from '../modules/pipelines/schema.ts'
+export * from '../modules/deals/schema.ts'
+export * from '../modules/opportunities/schema.ts'
+export * from '../modules/partnerships/schema.ts'
+export * from '../modules/raises/schema.ts'
+export * from '../modules/hiring/schema.ts'
+export * from '../modules/plans/schema.ts'
+export * from '../modules/decisions/schema.ts'
+export * from '../modules/notes/schema.ts'
+export * from '../modules/activities/schema.ts'
+export * from '../modules/handbook/schema.ts'
+export * from '../modules/forms/schema.ts'
+export * from '../modules/import-export/schema.ts'
+export * from '../modules/agent-tasks/schema.ts'
+export * from '../modules/webhooks/schema.ts'
+export * from '../modules/integrations/schema.ts'