@kelpie/server 0.6.0 → 0.8.0

package/migrations/meta/_journal.json

@@ -134,6 +134,41 @@
       "when": 1786656430307,
       "tag": "0018_hard_mystique",
       "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1787446086593,
+      "tag": "0019_sharp_red_skull",
+      "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1787447911296,
+      "tag": "0020_early_nemesis",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1787527717966,
+      "tag": "0021_certain_maggott",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1787626585359,
+      "tag": "0022_stormy_manta",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1787651539093,
+      "tag": "0023_funny_maddog",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelpie/server",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The Kelpie service as a library: module runtime, core CRM modules, REST API, MCP surface, and the shared migration pipeline.",
   "keywords": [
     "kelpie",
@@ -52,11 +52,12 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.12",
-    "@kelpie/schemas": "^0.6.0",
+    "@kelpie/schemas": "^0.8.0",
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "emittery": "^2.0.0",
     "hono": "^4.12.32",
+    "mailgen": "^2.0.36",
     "nodemailer": "^9.0.5",
     "postgres": "^3.4.9",
     "ulid": "^3.0.2",

package/src/app.ts

@@ -2,6 +2,7 @@ import { Hono } from 'hono'
 import type { Context } from 'hono'
 import { cors } from 'hono/cors'
 
+import type { RuntimeMode } from './lib/config.ts'
 import type { DatabaseProbe } from './lib/database.ts'
 import { AppError, internalErrorBody, toErrorBody } from './lib/errors.ts'
 import { PUBLIC_ROUTE_PREFIX } from './lib/http.ts'
@@ -51,6 +52,18 @@ export interface AppDependencies {
    * control (`testing/app.ts`).
    */
   readonly resolveClientIp: (context: Context) => string
+  /**
+   * Reported through `GET /v1/public/config` so the browser knows which
+   * runtime it is talking to. Defaults to `'production'` so a caller that has
+   * not thought about it fails safe: no banner shows.
+   */
+  readonly runtimeMode?: RuntimeMode
+  /**
+   * Reported through `GET /v1/public/config` so a non-production UI can name
+   * the site it is on. Undefined is fine and means "this deployment did not
+   * name itself".
+   */
+  readonly siteName?: string | undefined
 }
 
 /** Per-request values the middleware chain sets and handlers read. */
@@ -161,6 +174,19 @@ export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
     app.route(PUBLIC_ROUTE_PREFIX, router)
   }
 
+  // Public deployment metadata the browser reads once at boot. Sits under the
+  // public prefix so the CORS and rate-limit layers above cover it, and takes
+  // no credentials for the same reason /healthz does not: the pages that read
+  // it include the sign-in page, which runs before any session exists. The
+  // runtime mode is already visible in error messages, and the site name
+  // exists to be visible; nothing here is sensitive.
+  const runtimeMode: RuntimeMode = dependencies.runtimeMode ?? 'production'
+  const siteName = dependencies.siteName ?? null
+
+  app.get(`${PUBLIC_ROUTE_PREFIX}/config`, (context) =>
+    context.json({ runtime_mode: runtimeMode, site_name: siteName }, 200),
+  )
+
   for (const { router } of dependencies.contributions.routers) {
     app.route('/v1', router)
   }

package/src/boot.ts

@@ -0,0 +1,89 @@
+import type { Environment, KelpieConfig } from './lib/config.ts'
+import { connectDatabase } from './lib/database.ts'
+import type { DatabaseConnection } from './lib/database.ts'
+import { createIdFactory } from './lib/ids.ts'
+import type { IdFactory } from './lib/ids.ts'
+import { resolveKelpieConfig } from './lib/kelpieConfigFile.ts'
+import type { KelpieConfigInput } from './lib/kelpieConfigFile.ts'
+import { createLogger, createTransportForDestination } from './lib/logger.ts'
+import type { Logger } from './lib/logger.ts'
+import { readModuleConfigFile } from './lib/moduleConfig.ts'
+import { resolveActorFrom } from './modules/auth/credentials.ts'
+import type { CredentialDependencies } from './modules/auth/credentials.ts'
+import { createEventBus } from './runtime/events.ts'
+import { registerModules } from './runtime/registry.ts'
+import type { ModuleContributions } from './runtime/registry.ts'
+import { createTransactionScope } from './runtime/transaction.ts'
+
+/**
+ * A resolved assembly: config parsed, database connected, modules registered.
+ *
+ * This is the common prelude every entry point needs before it does its own
+ * work. `server.ts` goes on to build the app and serve; `migrate.ts` goes on to
+ * apply migrations and exit. Both start here, so the wiring lives in one place
+ * rather than drifting between two copies.
+ *
+ * The database is connected but not opened: postgres.js connects lazily, and
+ * registration issues no query, so a caller that only needs the contributions
+ * pays for no connection. The caller owns `database.close()`.
+ */
+export interface AssemblyBoot {
+  readonly config: KelpieConfig
+  readonly logger: Logger
+  readonly database: DatabaseConnection
+  readonly createId: IdFactory
+  readonly credentials: CredentialDependencies
+  readonly contributions: ModuleContributions
+}
+
+/**
+ * Resolves an assembly's config, connects the database, and runs the module
+ * registration pass.
+ *
+ * Registration touches no database. It only collects what the modules
+ * contribute, migrations directories included, which is why an entry point can
+ * call this and then decide whether to serve, migrate, or both.
+ *
+ * @throws ConfigurationError when a required variable is missing or malformed.
+ * @throws ModuleConfigFileError when the module override file cannot be read.
+ * @throws ModuleBootError when the module list is invalid or a module fails to
+ *   register. The caller maps these to a fix hint and an exit code.
+ */
+export async function bootAssembly(
+  kelpieConfig: KelpieConfigInput,
+  environment: Environment,
+): Promise<AssemblyBoot> {
+  const config = resolveKelpieConfig(kelpieConfig, environment)
+  const logger = createLogger({
+    level: config.logging.level,
+    transports: config.logging.destinations.map(createTransportForDestination),
+  })
+  const database = connectDatabase(config.databaseUrl, logger)
+  const events = createEventBus(logger)
+  const createId = createIdFactory()
+  const credentials: CredentialDependencies = { db: database.db, now: () => new Date() }
+  const moduleConfig = readModuleConfigFile(config.moduleConfigPath)
+  const contributions = await registerModules({
+    modules: kelpieConfig.modules,
+    environment: config.env,
+    logger,
+    events,
+    moduleConfig,
+    resolveActor: (context) => resolveActorFrom(credentials, context),
+    services: {
+      db: database.db,
+      transaction: createTransactionScope({ db: database.db, bus: events, logger, createId }),
+      createId,
+      now: () => new Date(),
+      appBaseUrl: config.appBaseUrl,
+      secretEncryption: config.secretEncryption,
+    },
+    // `provider` picks a named sender from the runtime's registry. `'log'` is
+    // built in; `'smtp'` is registered by the built-in `smtp-email` core
+    // module; other names come from third-party provider modules listed in
+    // `kelpie.config.ts`. `from` is the address on every outgoing message.
+    email: { provider: config.email.EMAIL_PROVIDER, from: config.email.EMAIL_FROM },
+  })
+
+  return { config, logger, database, createId, credentials, contributions }
+}

package/src/index.ts

@@ -1,6 +1,14 @@
+// Carries each module's `KelpieEventMap` augmentation into the emitted
+// `index.d.ts` so consumers installed from npm get a typed `event.data`. See
+// `modules/eventCatalogs.ts` for why the entry point has to reference them.
+import './modules/eventCatalogs.ts'
+
 export { createApp } from './app.ts'
 export type { AppDependencies, AppBindings } from './app.ts'
 
+export { bootAssembly } from './boot.ts'
+export type { AssemblyBoot } from './boot.ts'
+
 export { WebBundleError, serveWebBundle } from './webBundle.ts'
 export type { WebBundleOptions } from './webBundle.ts'
 

package/src/lib/config.ts

@@ -39,6 +39,13 @@ export interface KelpieConfig {
   readonly runtimeMode: RuntimeMode
   readonly port: number
   readonly databaseUrl: string
+  /**
+   * Human-readable name of this deployment ("dev", "demo", "cloud", or
+   * whatever the self-hoster picks). Undefined is normal. Exposed to the
+   * browser through `GET /v1/public/config` so a non-production UI can name
+   * the site it is on. Ignored when `runtimeMode` is `production`.
+   */
+  readonly siteName: string | undefined
   readonly logging: LoggingConfig
   /**
    * The provider name the module runtime looks up in its registry, and the
@@ -119,6 +126,7 @@ const environmentSchema = z.object({
     .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(),
+  KELPIE_SITE_NAME: z.string().min(1).optional(),
   WEB_BUNDLE_DIR: z.string().min(1).optional(),
   TRUSTED_PROXY_HOP_COUNT: z.coerce.number().int().nonnegative().default(0),
   ...rateLimitConfigSchema.shape,
@@ -156,6 +164,7 @@ export function loadConfig(environment: Environment): KelpieConfig {
     },
     email: emailResult.data,
     moduleConfigPath: environmentResult.data.KELPIE_MODULE_CONFIG_PATH,
+    siteName: environmentResult.data.KELPIE_SITE_NAME,
     webBundleDirectory: environmentResult.data.WEB_BUNDLE_DIR,
     rateLimit: rateLimitConfigFrom(environmentResult.data),
     trustedProxyHopCount: environmentResult.data.TRUSTED_PROXY_HOP_COUNT,

package/src/lib/consumerEmailDomains.ts

@@ -0,0 +1,62 @@
+/**
+ * Consumer email hosts, checked case-insensitively.
+ *
+ * The email-domain listener refuses to auto-link a Person to a Company on any
+ * domain in this list. A consumer address belongs to no one company, and a
+ * Company row entered by mistake against, say, `gmail.com` would otherwise
+ * auto-attach every consumer address after.
+ *
+ * A starter list of the common providers. Add locale variants and less common
+ * hosts as the need arrives.
+ */
+const CONSUMER_EMAIL_DOMAINS: ReadonlySet<string> = new Set([
+  'gmail.com',
+  'googlemail.com',
+  'yahoo.com',
+  'yahoo.co.uk',
+  'yahoo.co.jp',
+  'yahoo.fr',
+  'yahoo.de',
+  'yahoo.ca',
+  'yahoo.com.au',
+  'ymail.com',
+  'rocketmail.com',
+  'hotmail.com',
+  'hotmail.co.uk',
+  'hotmail.fr',
+  'hotmail.de',
+  'hotmail.it',
+  'hotmail.es',
+  'outlook.com',
+  'outlook.co.uk',
+  'live.com',
+  'live.co.uk',
+  'msn.com',
+  'aol.com',
+  'aim.com',
+  'icloud.com',
+  'me.com',
+  'mac.com',
+  'protonmail.com',
+  'proton.me',
+  'pm.me',
+  'gmx.com',
+  'gmx.net',
+  'gmx.de',
+  'mail.com',
+  'fastmail.com',
+  'fastmail.fm',
+  'zoho.com',
+  'yandex.com',
+  'yandex.ru',
+  'tutanota.com',
+  'tuta.io',
+  'qq.com',
+  '163.com',
+  '126.com',
+  'naver.com',
+])
+
+export function isConsumerEmailDomain(domain: string): boolean {
+  return CONSUMER_EMAIL_DOMAINS.has(domain.trim().toLowerCase())
+}

package/src/lib/email.ts

@@ -21,7 +21,14 @@ import type { Logger } from './logger.ts'
 export interface EmailMessage {
   readonly to: string
   readonly subject: string
+  /** The plaintext part. Always present: text-only clients and logs read it. */
   readonly body: string
+  /**
+   * The HTML alternative, rendered by `lib/emailContent.ts`. Optional so
+   * provider modules written against the older port keep compiling and a
+   * plain-text message stays expressible.
+   */
+  readonly html?: string
 }
 
 export interface EmailSender {

package/src/lib/emailContent.ts

@@ -0,0 +1,91 @@
+import Mailgen from 'mailgen'
+
+/**
+ * Renders transactional mail bodies: a plaintext part and an HTML part from
+ * one description of the message.
+ *
+ * Email clients need table-based, inline-styled HTML; mailgen owns that
+ * problem so Kelpie does not. The plaintext part is built here by hand rather
+ * than by mailgen's plaintext generator, because that generator pads lines
+ * with trailing whitespace and the plaintext body is the part tests and
+ * text-only clients read token links out of. The wording of the two parts
+ * comes from the same fields, so they cannot drift.
+ */
+
+/** A link the message asks the reader to follow, rendered as a button in HTML. */
+export interface EmailAction {
+  readonly instructions: string
+  readonly buttonText: string
+  readonly link: string
+}
+
+export interface EmailContent {
+  readonly intro?: string
+  readonly action?: EmailAction
+  readonly outro?: string
+}
+
+export interface RenderedEmail {
+  readonly text: string
+  readonly html: string
+}
+
+/**
+ * Fixed so rendering is deterministic. Mailgen's default footer stamps the
+ * current year, which the sender has no claim to: the workspace, not Kelpie,
+ * owns the relationship with the recipient.
+ */
+const FOOTER_LINE = 'Sent by Kelpie.'
+
+/**
+ * Renders one transactional message. `appBaseUrl` becomes the link on the
+ * product name in the header and footer, so every part of the mail points at
+ * the deployment that sent it.
+ */
+export function renderEmail(content: EmailContent, appBaseUrl: string): RenderedEmail {
+  const generator = new Mailgen({
+    theme: 'default',
+    product: {
+      name: 'Kelpie',
+      link: appBaseUrl,
+      copyright: FOOTER_LINE,
+    },
+  })
+
+  const html: string = generator.generate({
+    body: {
+      greeting: false,
+      signature: false,
+      ...(content.intro === undefined ? {} : { intro: content.intro }),
+      ...(content.action === undefined
+        ? {}
+        : {
+            action: {
+              instructions: content.action.instructions,
+              button: {
+                text: content.action.buttonText,
+                link: content.action.link,
+                fallback: true,
+              },
+            },
+          }),
+      ...(content.outro === undefined ? {} : { outro: content.outro }),
+    },
+  })
+
+  const paragraphs: string[] = []
+
+  if (content.intro !== undefined) {
+    paragraphs.push(content.intro)
+  }
+
+  if (content.action !== undefined) {
+    paragraphs.push(`${content.action.instructions}\n\n${content.action.link}`)
+  }
+
+  if (content.outro !== undefined) {
+    paragraphs.push(content.outro)
+  }
+
+  return { text: paragraphs.join('\n\n'), html }
+}

package/src/lib/emailDomainAutoLink.ts

@@ -0,0 +1,165 @@
+import { UNIQUE_VIOLATION, postgresErrorCode } from './database.ts'
+import type { IdFactory } from './ids.ts'
+import { isConsumerEmailDomain } from './consumerEmailDomains.ts'
+import type { BufferedEvents, Transaction } from '../runtime/transaction.ts'
+import type { ActivityRecorder, SystemActor } from '../modules/activities/recorder.ts'
+import { describeLink } from '../modules/activities/wording.ts'
+import * as companyRepository from '../modules/companies/repository.ts'
+import type { CompanyRecord } from '../modules/companies/repository.ts'
+import * as peopleRepository from '../modules/people/repository.ts'
+import type { PersonRecord } from '../modules/people/repository.ts'
+import '../modules/positions/events.ts'
+import * as positionRepository from '../modules/positions/repository.ts'
+
+/**
+ * Auto-link a Person to a workspace Company whose domain matches the person's
+ * email. Runs inside the caller's transaction, so the new Position is present
+ * in the response the API returns for the same request.
+ *
+ * Skips: no email, consumer email host (`isConsumerEmailDomain`), no Company
+ * on that domain in the workspace, or a Position already linking the two. A
+ * unique-key race with a concurrent linker is absorbed.
+ *
+ * The created Position carries an empty title. `positions.title` is `NOT NULL`,
+ * and empty reads honestly as "the domain matched; no title yet".
+ *
+ * Split from the people service so the layering (people below positions) is
+ * carried by imports only: this helper depends on both repositories, and the
+ * people service depends on this helper. The `positions` module still owns the
+ * event catalogue for the emitted event.
+ */
+
+/** What the timeline calls this side effect. */
+const LINKER_ACTOR: SystemActor = { kind: 'system', label: 'Email domain match' }
+
+export interface AutoLinkDependencies {
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/**
+ * Considers `person` for a matching Company in `workspaceId` and inserts a
+ * titleless Position if none links them yet.
+ *
+ * @returns The new Position's id, or `undefined` if nothing was written.
+ */
+export async function autoLinkPersonByEmailDomain(
+  tx: Transaction,
+  events: BufferedEvents,
+  workspaceId: string,
+  person: PersonRecord,
+  dependencies: AutoLinkDependencies,
+): Promise<string | undefined> {
+  if (person.email === null) {
+    return undefined
+  }
+
+  const at = person.email.indexOf('@')
+  if (at < 0) {
+    return undefined
+  }
+
+  const domain = person.email.slice(at + 1)
+  if (domain.length === 0 || isConsumerEmailDomain(domain)) {
+    return undefined
+  }
+
+  const company = await companyRepository.findCompanyByDomain(tx, workspaceId, domain)
+  if (company === undefined) {
+    return undefined
+  }
+
+  const held = await positionRepository.listPositionsAt(tx, workspaceId, person.id, company.id)
+  if (held.length > 0) {
+    return undefined
+  }
+
+  return insertStubPosition(tx, events, workspaceId, person, company, dependencies)
+}
+
+/**
+ * Sweeps every Person in `workspaceId` whose email domain matches `company`'s
+ * domain and stubs a Position where none exists yet. Called when a Company is
+ * created or its domain is set.
+ *
+ * @returns The ids of every Position this call inserted.
+ */
+export async function autoLinkCompanyByDomain(
+  tx: Transaction,
+  events: BufferedEvents,
+  workspaceId: string,
+  company: CompanyRecord,
+  dependencies: AutoLinkDependencies,
+): Promise<readonly string[]> {
+  if (company.domain === null || company.domain.length === 0) {
+    return []
+  }
+
+  if (isConsumerEmailDomain(company.domain)) {
+    return []
+  }
+
+  const matches = await peopleRepository.findPeopleByEmailDomain(tx, workspaceId, company.domain)
+  const created: string[] = []
+
+  for (const person of matches) {
+    const held = await positionRepository.listPositionsAt(tx, workspaceId, person.id, company.id)
+    if (held.length > 0) {
+      continue
+    }
+
+    const id = await insertStubPosition(tx, events, workspaceId, person, company, dependencies)
+    if (id !== undefined) {
+      created.push(id)
+    }
+  }
+
+  return created
+}
+
+/**
+ * The write half. Wraps the unique-constraint race the two entry points share:
+ * a concurrent linker that beat us to `(personId, companyId, '')` is treated
+ * as success (the link is there, either way).
+ */
+async function insertStubPosition(
+  tx: Transaction,
+  events: BufferedEvents,
+  workspaceId: string,
+  person: PersonRecord,
+  company: CompanyRecord,
+  dependencies: AutoLinkDependencies,
+): Promise<string | undefined> {
+  try {
+    const created = await positionRepository.insertPosition(tx, {
+      id: dependencies.createId('position'),
+      workspaceId,
+      personId: person.id,
+      companyId: company.id,
+      title: '',
+    })
+
+    await dependencies.recordActivity(tx, workspaceId, LINKER_ACTOR, {
+      targetType: 'person',
+      targetId: person.id,
+      kind: 'linked',
+      ...describeLink('company', company.name),
+    })
+    await dependencies.recordActivity(tx, workspaceId, LINKER_ACTOR, {
+      targetType: 'company',
+      targetId: company.id,
+      kind: 'linked',
+      ...describeLink('person', person.name),
+    })
+
+    events.emit('positions.position.created', { type: 'position', id: created.id }, {})
+
+    return created.id
+  } catch (error: unknown) {
+    if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+      return undefined
+    }
+    throw error
+  }
+}

package/src/lib/ids.ts

@@ -28,6 +28,8 @@ export const idPrefixes = {
   decision: 'dec',
   note: 'note',
   activity: 'act',
+  list: 'list',
+  listMember: 'lmem',
   handbookPage: 'hb',
   form: 'form',
   formField: 'ff',

package/src/lib/kelpieConfigFile.ts

@@ -27,6 +27,12 @@ export interface KelpieConfigInput {
   readonly webBundleDirectory?: ConfigValue<string | undefined>
   /** Optional; unset in development, set to the deploy-time module override file. */
   readonly moduleConfigPath?: ConfigValue<string | undefined>
+  /**
+   * Human-readable name of this deployment ("dev", "demo", "cloud"). Optional.
+   * Read by the browser through `GET /v1/public/config` so a non-production UI
+   * can name the site it is on. Ignored when `runtimeMode` is `production`.
+   */
+  readonly siteName?: ConfigValue<string | undefined>
   /** Optional; defaults to 0 (no proxy in front). */
   readonly trustedProxyHopCount?: ConfigValue<number>
   /**
@@ -173,6 +179,7 @@ export function resolveKelpieConfig(input: KelpieConfigInput, environment: Envir
     },
     email,
     moduleConfigPath: resolved.moduleConfigPath,
+    siteName: resolved.siteName,
     webBundleDirectory: resolved.webBundleDirectory,
     rateLimit,
     trustedProxyHopCount: resolved.trustedProxyHopCount ?? 0,
@@ -208,6 +215,7 @@ interface ResolvedInput {
   }
   readonly webBundleDirectory?: string | undefined
   readonly moduleConfigPath?: string | undefined
+  readonly siteName?: string | undefined
   readonly trustedProxyHopCount?: number
   readonly appBaseUrl?: string
   readonly secretEncryption?: ResolvedSecretEncryption

package/src/modules/attachedRecords.ts

@@ -6,6 +6,7 @@ import type { Queryable } from '../runtime/transaction.ts'
 import * as activityRepository from './activities/repository.ts'
 import * as decisionRepository from './decisions/repository.ts'
 import { candidates } from './hiring/schema.ts'
+import * as listRepository from './lists/repository.ts'
 import * as noteRepository from './notes/repository.ts'
 import * as planRepository from './plans/repository.ts'
 
@@ -37,7 +38,7 @@ export async function deleteRecordsAttachedTo(
   targetType: AttachableTargetType,
   targetId: string,
 ): Promise<number> {
-  // Sequential, not concurrent: a transaction is one connection, and four
+  // Sequential, not concurrent: a transaction is one connection, and five
   // statements racing down it is not something to rely on for a cheap delete.
   const notes = await noteRepository.deleteForTarget(db, workspaceId, targetType, targetId)
   const activities = await activityRepository.deleteForTarget(db, workspaceId, targetType, targetId)
@@ -45,8 +46,14 @@ export async function deleteRecordsAttachedTo(
   const plans = PLAN_TARGET_TYPES.has(targetType)
     ? await planRepository.deleteForTarget(db, workspaceId, targetType, targetId)
     : 0
+  const memberships = await listRepository.deleteMembershipsForTarget(
+    db,
+    workspaceId,
+    targetType,
+    targetId,
+  )
 
-  return notes + activities + decisions + plans
+  return notes + activities + decisions + plans + memberships
 }
 
 /**