@kelpie/server 0.1.0

package/src/modules/workspace/starters.ts

@@ -0,0 +1,69 @@
+/**
+ * What a new workspace starts with, per `onboarding.md` step 4 and the seeding
+ * rule in `schema.md`.
+ *
+ * Both lists are data, not migrations: they are per-workspace rows a workspace
+ * owner can then rename, reorder, or delete.
+ */
+
+export interface StarterHandbookPage {
+  readonly title: string
+  readonly slug: string
+}
+
+/** Bodies start as stubs. Teams write them; agents read whatever is there. */
+export const STARTER_HANDBOOK_PAGES: readonly StarterHandbookPage[] = [
+  { title: 'About us', slug: 'about-us' },
+  { title: 'Product', slug: 'product' },
+  { title: 'Ideal customer profile', slug: 'ideal-customer-profile' },
+  { title: 'Voice and tone', slug: 'voice-and-tone' },
+  { title: 'Pricing', slug: 'pricing' },
+  { title: 'How we sell', slug: 'how-we-sell' },
+  { title: 'Competitive landscape', slug: 'competitive-landscape' },
+  { title: 'Team and roles', slug: 'team-and-roles' },
+  { title: 'Tools and stack', slug: 'tools-and-stack' },
+  { title: 'Agent FAQ', slug: 'agent-faq' },
+]
+
+export function starterHandbookBody(title: string): string {
+  return `# ${title}\n\nWrite this page.`
+}
+
+export interface StarterStage {
+  readonly slug: string
+  readonly label: string
+  readonly open: boolean
+}
+
+/** `open: false` hides a stage from the Open scope filter; it is not a delete. */
+export const STARTER_PIPELINE_STAGES: Readonly<Record<string, readonly StarterStage[]>> = {
+  deal: [
+    { slug: 'qualifying', label: 'Qualifying', open: true },
+    { slug: 'proposal', label: 'Proposal', open: true },
+    { slug: 'negotiation', label: 'Negotiation', open: true },
+    { slug: 'won', label: 'Won', open: false },
+    { slug: 'lost', label: 'Lost', open: false },
+  ],
+  opportunity: [
+    { slug: 'identified', label: 'Identified', open: true },
+    { slug: 'applied', label: 'Applied', open: true },
+    { slug: 'interview', label: 'Interview', open: true },
+    { slug: 'won', label: 'Won', open: false },
+    { slug: 'passed', label: 'Passed', open: false },
+  ],
+  raise: [
+    { slug: 'researching', label: 'Researching', open: true },
+    { slug: 'intro', label: 'Intro', open: true },
+    { slug: 'meeting', label: 'Meeting', open: true },
+    { slug: 'diligence', label: 'Diligence', open: true },
+    { slug: 'term_sheet', label: 'Term sheet', open: true },
+    { slug: 'closed', label: 'Closed', open: false },
+    { slug: 'passed', label: 'Passed', open: false },
+  ],
+  partnership: [
+    { slug: 'exploring', label: 'Exploring', open: true },
+    { slug: 'active', label: 'Active', open: true },
+    { slug: 'paused', label: 'Paused', open: true },
+    { slug: 'ended', label: 'Ended', open: false },
+  ],
+}

package/src/modules/workspace/tools.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod'
+
+import { requireWorkspaceId } from '../../lib/actor.ts'
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { deleteResult, idArg } from '../crudTools.ts'
+import { inviteBody, inviteResponse, memberResponse, memberRoleBody, resendBody, updateBody, workspaceResponse } from './routes.ts'
+import type { WorkspaceService } from './service.ts'
+
+/**
+ * `workspace_*`: settings, the team, and invitations.
+ *
+ * No workspace id argument anywhere. `api.md` makes the workspace implicit, a key
+ * is bound to one at creation, and `/v1/workspaces/{id}` carries the id only
+ * because a path needs a subject. Taking one here would offer a caller a choice
+ * it does not have.
+ *
+ * Three REST operations have no tool. Creating a workspace and accepting an
+ * invitation both need a browser session, which this endpoint does not take, and
+ * a key issued for one workspace could not act on the new one anyway. Deleting a
+ * workspace destroys everything the calling key is scoped to, and asking an agent
+ * to confirm a slug is not a safeguard when the agent can read the slug.
+ */
+
+const noArgs = z.strictObject({})
+
+export function registerWorkspaceTools(mcp: McpToolRegistry, service: WorkspaceService): void {
+  mcp.tool({
+    name: 'workspace_get',
+    description:
+      'This workspace\'s name, slug, timezone, tagline and one-liner. Mirrors GET /v1/workspaces/{id}.',
+    inputSchema: noArgs,
+    invoke: async (_args, actor) =>
+      workspaceResponse(await service.get(actor, requireWorkspaceId(actor))),
+  })
+
+  mcp.tool({
+    name: 'workspace_update',
+    description:
+      'Change this workspace\'s settings. Admin only. Mirrors PATCH /v1/workspaces/{id}.',
+    inputSchema: updateBody,
+    invoke: async (changes, actor) =>
+      workspaceResponse(await service.update(actor, requireWorkspaceId(actor), changes)),
+  })
+
+  mcp.tool({
+    name: 'workspace_members_list',
+    description:
+      'Everyone on this workspace, with their role. Use a member id here as the owner_id on a ' +
+      'deal or a plan item. Mirrors GET /v1/workspaces/{id}/members.',
+    inputSchema: noArgs,
+    invoke: async (_args, actor) => ({
+      data: (await service.listMembers(actor, requireWorkspaceId(actor))).map(memberResponse),
+      next_cursor: null,
+    }),
+  })
+
+  mcp.tool({
+    name: 'workspace_members_set_role',
+    description:
+      'Change a member\'s role. Setting owner transfers ownership, which is a single seat. ' +
+      'Admin only. Mirrors PATCH /v1/workspaces/{id}/members/{memberId}.',
+    inputSchema: memberRoleBody.extend({ member_id: idArg }),
+    invoke: async (args, actor) =>
+      memberResponse(
+        await service.setMemberRole(actor, requireWorkspaceId(actor), args.member_id, args.role),
+      ),
+  })
+
+  mcp.tool({
+    name: 'workspace_members_remove',
+    description:
+      'Remove somebody from this workspace. Admin only. ' +
+      'Mirrors DELETE /v1/workspaces/{id}/members/{memberId}.',
+    inputSchema: z.strictObject({ member_id: idArg }),
+    invoke: async ({ member_id: memberId }, actor) => {
+      await service.removeMember(actor, requireWorkspaceId(actor), memberId)
+
+      return deleteResult(memberId)
+    },
+  })
+
+  mcp.tool({
+    name: 'workspace_invites_create',
+    description:
+      'Invite somebody by email and send them the invitation. invite_url_template is the page ' +
+      'that accepts it and must contain {token}. Admin only. ' +
+      'Mirrors POST /v1/workspaces/{id}/invites.',
+    inputSchema: inviteBody,
+    invoke: async (body, actor) =>
+      inviteResponse(
+        await service.invite(
+          actor,
+          requireWorkspaceId(actor),
+          body.email,
+          body.role,
+          body.invite_url_template,
+        ),
+      ),
+  })
+
+  mcp.tool({
+    name: 'workspace_invites_list',
+    description:
+      'Outstanding and spent invitations. Mirrors GET /v1/workspaces/{id}/invites.',
+    inputSchema: noArgs,
+    invoke: async (_args, actor) => ({
+      data: (await service.listInvites(actor, requireWorkspaceId(actor))).map(inviteResponse),
+      next_cursor: null,
+    }),
+  })
+
+  mcp.tool({
+    name: 'workspace_invites_resend',
+    description:
+      'Issue a fresh token and expiry for an invitation and email it again. Admin only. ' +
+      'Mirrors POST /v1/workspaces/{id}/invites/{inviteId}/resend.',
+    inputSchema: resendBody.extend({ invite_id: idArg }),
+    invoke: async (args, actor) =>
+      inviteResponse(
+        await service.resendInvite(
+          actor,
+          requireWorkspaceId(actor),
+          args.invite_id,
+          args.invite_url_template,
+        ),
+      ),
+  })
+
+  mcp.tool({
+    name: 'workspace_invites_revoke',
+    description:
+      'Withdraw an invitation that has not been accepted. Admin only. ' +
+      'Mirrors DELETE /v1/workspaces/{id}/invites/{inviteId}.',
+    inputSchema: z.strictObject({ invite_id: idArg }),
+    invoke: async ({ invite_id: inviteId }, actor) => {
+      await service.revokeInvite(actor, requireWorkspaceId(actor), inviteId)
+
+      return deleteResult(inviteId)
+    },
+  })
+}

package/src/runtime/entitlements.ts

@@ -0,0 +1,142 @@
+import { AppError } from '../lib/errors.ts'
+import { ModuleBootError } from './order.ts'
+
+/**
+ * Feature gating that stays inert in open source.
+ *
+ * Modules and core declare capabilities. Services check them where gating
+ * matters. The open-source assembly registers no grant provider, so every check
+ * answers granted and unlimited: a self-hoster never meets a paywall.
+ *
+ * The cloud billing module supplies a provider that maps subscription state to
+ * grants. Nothing else about the check changes.
+ */
+
+/** A yes-or-no capability, e.g. `integrations.gmail`. */
+export interface FlagCapability {
+  readonly name: string
+  readonly kind: 'flag'
+  readonly description: string
+}
+
+/** A counted capability, e.g. `seats.limit`. */
+export interface LimitCapability {
+  readonly name: string
+  readonly kind: 'limit'
+  readonly description: string
+}
+
+export type Capability = FlagCapability | LimitCapability
+
+/** What a check answers. `limit: null` means unlimited, not zero. */
+export type Entitlement =
+  | { readonly kind: 'flag'; readonly granted: boolean }
+  | { readonly kind: 'limit'; readonly limit: number | null }
+
+/**
+ * Supplies grants for a workspace.
+ *
+ * @returns The grant, or undefined to express no opinion and let the next
+ *   provider, or the open-source default, answer.
+ */
+export type GrantProvider = (
+  workspaceId: string,
+  capability: Capability,
+) => Promise<Entitlement | undefined>
+
+export interface EntitlementRegistry {
+  /** Declares a capability. Declaring one name twice fails boot. */
+  declare(capability: Capability): void
+  /** Registers a source of grants. Providers are asked in registration order. */
+  provide(provider: GrantProvider): void
+  /**
+   * @throws AppError 500 if nothing declared this capability, which means a typo
+   *   rather than a missing grant.
+   */
+  check(workspaceId: string, name: string): Promise<Entitlement>
+  /** Everything declared, for an admin page or a support answer. */
+  capabilities(): readonly Capability[]
+}
+
+/** What a capability answers when no provider has an opinion. */
+function openSourceDefault(capability: Capability): Entitlement {
+  return capability.kind === 'flag' ? { kind: 'flag', granted: true } : { kind: 'limit', limit: null }
+}
+
+export function createEntitlementRegistry(): EntitlementRegistry {
+  const declared = new Map<string, Capability>()
+  const providers: GrantProvider[] = []
+
+  return {
+    declare(capability) {
+      if (declared.has(capability.name)) {
+        throw new ModuleBootError([`capability "${capability.name}" is declared twice`])
+      }
+
+      declared.set(capability.name, capability)
+    },
+
+    provide(provider) {
+      providers.push(provider)
+    },
+
+    async check(workspaceId, name) {
+      const capability = declared.get(name)
+
+      if (capability === undefined) {
+        throw new Error(`No module declared the capability "${name}"`)
+      }
+
+      for (const provider of providers) {
+        const grant = await provider(workspaceId, capability)
+
+        if (grant !== undefined) {
+          return grant
+        }
+      }
+
+      return openSourceDefault(capability)
+    },
+
+    capabilities() {
+      return [...declared.values()]
+    },
+  }
+}
+
+/**
+ * Guards a gated action.
+ *
+ * @throws AppError 403 `entitlement_required` when the capability is not granted.
+ */
+export async function requireCapability(
+  entitlements: EntitlementRegistry,
+  workspaceId: string,
+  name: string,
+): Promise<void> {
+  const entitlement = await entitlements.check(workspaceId, name)
+
+  if (entitlement.kind === 'flag' && !entitlement.granted) {
+    throw new AppError('entitlement_required', `Your plan does not include ${name}`)
+  }
+}
+
+/**
+ * Reads a counted capability.
+ *
+ * @returns The limit, or null for unlimited.
+ * @throws Error if the capability was declared as a flag rather than a limit.
+ */
+export async function limitFor(
+  entitlements: EntitlementRegistry,
+  workspaceId: string,
+  name: string,
+): Promise<number | null> {
+  const entitlement = await entitlements.check(workspaceId, name)
+
+  if (entitlement.kind !== 'limit') {
+    throw new Error(`Capability "${name}" is a flag, not a limit`)
+  }
+
+  return entitlement.limit
+}

package/src/runtime/events.ts

@@ -0,0 +1,185 @@
+import { describeThrown } from '../lib/errors.ts'
+import type { Logger } from '../lib/logger.ts'
+
+/**
+ * In-process typed domain events, per `modules.md`.
+ *
+ * Delivery is at-least-once within the process, with no durable queue. A crash
+ * between commit and dispatch loses the event. A durable outbox is a known
+ * follow-up; do not build it before a consumer cannot tolerate the loss.
+ */
+
+/**
+ * CRM object types that `record.*` events carry. Every object the API writes,
+ * including the link and content records.
+ *
+ * Wider than `EXTENSIBLE_RECORD_TYPES` in `@kelpie/schemas`, which is the
+ * shorter list of detail pages a UI module can contribute to. A Position, a
+ * Form, and a Handbook page each publish events but have no page to extend.
+ */
+export const RECORD_OBJECT_TYPES = [
+  'person',
+  'company',
+  'position',
+  'deal',
+  'opportunity',
+  'partnership',
+  'raise',
+  'role',
+  'candidate',
+  'handbook_page',
+  'form',
+] as const
+
+export type RecordObjectType = (typeof RECORD_OBJECT_TYPES)[number]
+
+/** Objects whose stage or status moves through a pipeline. */
+export type StagedObjectType = 'deal' | 'opportunity' | 'raise' | 'partnership'
+
+/**
+ * The event catalog. Every payload carries `workspaceId`: a consumer must never
+ * have to look up which tenant an event belongs to.
+ *
+ * Adding an event means adding a key here. The name is the key, so a typo is a
+ * compile error rather than a subscription that never fires.
+ */
+export interface DomainEvents {
+  'workspace.created': { workspaceId: string; slug: string }
+  /** Fires after the cascade, so nothing the workspace owned still exists. */
+  'workspace.deleted': { workspaceId: string; slug: string }
+  'member.invited': { workspaceId: string; inviteId: string; email: string }
+  'member.joined': { workspaceId: string; memberId: string; userId: string }
+  /** Pairs with `member.joined`, which is what a seat count subscribes to. */
+  'member.removed': { workspaceId: string; memberId: string; userId: string }
+  'record.created': { workspaceId: string; objectType: RecordObjectType; recordId: string }
+  'record.updated': {
+    workspaceId: string
+    objectType: RecordObjectType
+    recordId: string
+    changedFields: readonly string[]
+  }
+  'record.deleted': { workspaceId: string; objectType: RecordObjectType; recordId: string }
+  'stage.changed': {
+    workspaceId: string
+    objectType: StagedObjectType
+    recordId: string
+    fromStageId: string | null
+    toStageId: string
+  }
+  'note.added': { workspaceId: string; noteId: string; targetType: string; targetId: string }
+  'decision.added': { workspaceId: string; decisionId: string; targetType: string; targetId: string }
+  'plan.completed': { workspaceId: string; planItemId: string; targetType: string; targetId: string }
+  'form.submitted': { workspaceId: string; formId: string; submissionId: string }
+  'import.completed': { workspaceId: string; importJobId: string; object: string }
+  'agent_run.finished': { workspaceId: string; agentRunId: string; status: 'succeeded' | 'failed' }
+}
+
+export type DomainEventName = keyof DomainEvents
+
+/**
+ * The catalog as data. Webhooks needs the deliverable event names at runtime, and
+ * `satisfies` keeps this list from drifting from the interface above.
+ *
+ * An event added to `DomainEvents` but forgotten here is caught by
+ * `createHandlerRegistry`, which must produce an entry for every name.
+ */
+export const DOMAIN_EVENT_NAMES = [
+  'workspace.created',
+  'workspace.deleted',
+  'member.invited',
+  'member.joined',
+  'member.removed',
+  'record.created',
+  'record.updated',
+  'record.deleted',
+  'stage.changed',
+  'note.added',
+  'decision.added',
+  'plan.completed',
+  'form.submitted',
+  'import.completed',
+  'agent_run.finished',
+] as const satisfies readonly DomainEventName[]
+
+/** Handlers are async and must be idempotent: the same event may arrive twice. */
+export type EventHandler<Name extends DomainEventName> = (payload: DomainEvents[Name]) => Promise<void>
+
+export interface EventBus {
+  /** Registers a handler. Handlers for one event run concurrently, not in order. */
+  subscribe<Name extends DomainEventName>(name: Name, handler: EventHandler<Name>): void
+  /**
+   * Dispatches immediately. Services should not call this directly: they emit
+   * through the transaction scope so nothing fires before the commit.
+   *
+   * @returns A promise that settles when every handler for this event has settled.
+   */
+  publish<Name extends DomainEventName>(name: Name, payload: DomainEvents[Name]): Promise<void>
+  /**
+   * Settles once every in-flight publication has finished, including any a
+   * handler started. Used by tests, and by shutdown to flush before exit.
+   */
+  drain(): Promise<void>
+}
+
+/**
+ * A handler that throws must not break the emitting request, and must not stop
+ * its siblings. Failures are logged and dropped.
+ */
+/** One handler list per event, keyed so each list stays tied to its payload type. */
+type HandlerRegistry = { [Name in DomainEventName]: EventHandler<Name>[] }
+
+/**
+ * Every name gets a list up front. TypeScript cannot check a write through a
+ * generic key, so pre-seeding turns `subscribe` into a read plus a push, which it
+ * can check. The one assertion is building a complete record from its own key list.
+ */
+function createHandlerRegistry(): HandlerRegistry {
+  const registry: Partial<HandlerRegistry> = {}
+
+  for (const name of DOMAIN_EVENT_NAMES) {
+    registry[name] = []
+  }
+
+  return registry as HandlerRegistry
+}
+
+export function createEventBus(logger: Logger): EventBus {
+  const handlers = createHandlerRegistry()
+  const inFlight = new Set<Promise<void>>()
+
+  return {
+    subscribe(name, handler) {
+      handlers[name].push(handler)
+    },
+
+    publish(name, payload) {
+      const registered = handlers[name]
+
+      const settled = Promise.allSettled(registered.map((handler) => handler(payload))).then(
+        (outcomes) => {
+          for (const outcome of outcomes) {
+            if (outcome.status === 'rejected') {
+              logger.error('event handler failed', {
+                event: name,
+                error: describeThrown(outcome.reason),
+              })
+            }
+          }
+        },
+      )
+
+      inFlight.add(settled)
+      void settled.finally(() => inFlight.delete(settled))
+
+      return settled
+    },
+
+    async drain() {
+      // A handler may publish further events, so keep draining until the set is
+      // empty rather than awaiting one snapshot of it.
+      while (inFlight.size > 0) {
+        await Promise.allSettled([...inFlight])
+      }
+    },
+  }
+}

package/src/runtime/migrate.ts

@@ -0,0 +1,75 @@
+import { migrate } from 'drizzle-orm/postgres-js/migrator'
+
+import type { Database } from '../lib/database.ts'
+import type { Logger } from '../lib/logger.ts'
+import type { SchemaContribution } from './module.ts'
+
+/**
+ * Applies pending migrations for every directory the registered modules
+ * contributed.
+ *
+ * Core modules all share one directory, so directories are deduplicated and each
+ * runs once. Each gets its own migrations table: Drizzle tracks progress with a
+ * single high-water timestamp per table, so two directories sharing one would
+ * make the second silently skip anything older than the first's newest migration.
+ *
+ * Migrations are forward-only. Running this twice is a no-op.
+ */
+export interface MigrationPlanStep {
+  readonly migrationsDirectory: string
+  readonly migrationsTable: string
+  readonly moduleIds: readonly string[]
+}
+
+/** Postgres identifiers are 63 bytes; module ids are short, but hyphens are not legal unquoted. */
+function migrationsTableFor(moduleId: string): string {
+  return `__drizzle_migrations_${moduleId.replace(/[^a-z0-9]+/giu, '_').toLowerCase()}`
+}
+
+/**
+ * Groups schema contributions into one step per directory.
+ *
+ * Pure, so the plan can be asserted without a database. The first module to claim
+ * a directory names its migrations table; the rest ride along.
+ */
+export function planMigrations(contributions: readonly SchemaContribution[]): readonly MigrationPlanStep[] {
+  const steps = new Map<string, { migrationsTable: string; moduleIds: string[] }>()
+
+  for (const contribution of contributions) {
+    const existing = steps.get(contribution.migrationsDir)
+
+    if (existing === undefined) {
+      steps.set(contribution.migrationsDir, {
+        migrationsTable: migrationsTableFor(contribution.moduleId),
+        moduleIds: [contribution.moduleId],
+      })
+      continue
+    }
+
+    existing.moduleIds.push(contribution.moduleId)
+  }
+
+  return [...steps].map(([migrationsDirectory, step]) => ({
+    migrationsDirectory,
+    migrationsTable: step.migrationsTable,
+    moduleIds: step.moduleIds,
+  }))
+}
+
+export async function runMigrations(
+  db: Database,
+  contributions: readonly SchemaContribution[],
+  logger: Logger,
+): Promise<void> {
+  for (const step of planMigrations(contributions)) {
+    await migrate(db, {
+      migrationsFolder: step.migrationsDirectory,
+      migrationsTable: step.migrationsTable,
+    })
+
+    logger.info('migrations applied', {
+      directory: step.migrationsDirectory,
+      modules: step.moduleIds,
+    })
+  }
+}