@kelpie/server 0.1.0

package/src/modules/companies/tools.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import { companyResponse, createBody, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { CompaniesService } from './service.ts'
+
+/** `companies_*`. Same schemas and mappers as `/v1/companies`. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg,
+  person_id: idSetArg
+    .optional()
+    .describe('Only companies where one of these people holds a position.'),
+})
+
+export function registerCompaniesTools(mcp: McpToolRegistry, service: CompaniesService): void {
+  registerCrudTools(mcp, {
+    resource: 'companies',
+    subject: 'company',
+    about: 'An organisation, with the stage, ICP fit and tech stack an agent qualifies against.',
+    service,
+    render: companyResponse,
+    listArgs,
+    toFilters: (args) => ({ term: args.q, personIds: toSet(args.person_id) }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/core.ts

@@ -0,0 +1,93 @@
+import { fileURLToPath } from 'node:url'
+
+import type { KelpieModule } from '../runtime/module.ts'
+import { createActivitiesModule } from './activities/index.ts'
+import { createAgentTasksModule } from './agent-tasks/index.ts'
+import { createApiKeysModule } from './api-keys/index.ts'
+import { createAuthModule } from './auth/index.ts'
+import { createCompaniesModule } from './companies/index.ts'
+import { createDashboardModule } from './dashboard/index.ts'
+import { createDealsModule } from './deals/index.ts'
+import { createDecisionsModule } from './decisions/index.ts'
+import { createFormsModule } from './forms/index.ts'
+import { createHandbookModule } from './handbook/index.ts'
+import { createHiringModule } from './hiring/index.ts'
+import { createImportExportModule } from './import-export/index.ts'
+import * as integrations from './integrations/schema.ts'
+import { createNotesModule } from './notes/index.ts'
+import { createOpportunitiesModule } from './opportunities/index.ts'
+import { createPartnershipsModule } from './partnerships/index.ts'
+import { createPeopleModule } from './people/index.ts'
+import { createPipelinesModule } from './pipelines/index.ts'
+import { createPlansModule } from './plans/index.ts'
+import { createPositionsModule } from './positions/index.ts'
+import { createRaisesModule } from './raises/index.ts'
+import { createSearchModule } from './search/index.ts'
+import { createWebhooksModule } from './webhooks/index.ts'
+import { createWorkspaceModule } from './workspace/index.ts'
+
+/**
+ * The core feature modules, in the order `architecture.md` fixes. Core registers
+ * through the same runtime modules do; if core could not be built on these
+ * extension points, neither could anything else.
+ *
+ * Order matters for `requires` resolution and route registration. Nothing else
+ * about runtime behaviour may depend on it.
+ *
+ * Core shares one migrations directory. Drizzle Kit generates one ordered
+ * pipeline from the barrel in `src/schema`, so splitting it per module would mean
+ * one config per module for no gain. A module outside core brings its own.
+ */
+export const coreMigrationsDirectory = fileURLToPath(new URL('../../migrations', import.meta.url))
+
+interface CoreModuleDefinition {
+  readonly id: string
+  readonly requires?: readonly string[]
+  readonly tables: Readonly<Record<string, unknown>>
+}
+
+const definitions: readonly CoreModuleDefinition[] = [
+  { id: 'integrations', requires: ['workspace'], tables: integrations },
+]
+
+/**
+ * Modules with behaviour are written out; the rest contribute only tables so far
+ * and are generated from the table above. As each grows routes and services it
+ * moves out of `definitions` into its own module file, like `auth` has.
+ */
+export const coreModules: readonly KelpieModule[] = [
+  createAuthModule(coreMigrationsDirectory),
+  createWorkspaceModule(coreMigrationsDirectory),
+  createApiKeysModule(coreMigrationsDirectory),
+  createPeopleModule(coreMigrationsDirectory),
+  createCompaniesModule(coreMigrationsDirectory),
+  createPositionsModule(coreMigrationsDirectory),
+  createActivitiesModule(coreMigrationsDirectory),
+  createNotesModule(coreMigrationsDirectory),
+  createPipelinesModule(coreMigrationsDirectory),
+  createDealsModule(coreMigrationsDirectory),
+  createOpportunitiesModule(coreMigrationsDirectory),
+  createPartnershipsModule(coreMigrationsDirectory),
+  createRaisesModule(coreMigrationsDirectory),
+  createHiringModule(coreMigrationsDirectory),
+  createPlansModule(coreMigrationsDirectory),
+  createDecisionsModule(coreMigrationsDirectory),
+  createHandbookModule(coreMigrationsDirectory),
+  // Neither of these takes a migrations directory: they own no tables and read
+  // other modules'.
+  createSearchModule(),
+  createDashboardModule(),
+  createFormsModule(coreMigrationsDirectory),
+  createImportExportModule(coreMigrationsDirectory),
+  createAgentTasksModule(coreMigrationsDirectory),
+  createWebhooksModule(coreMigrationsDirectory),
+  ...definitions.map((definition): KelpieModule => ({
+    id: definition.id,
+    ...(definition.requires === undefined ? {} : { requires: definition.requires }),
+    register(context) {
+      context.schema(definition.tables, coreMigrationsDirectory)
+
+      return Promise.resolve()
+    },
+  })),
+]

package/src/modules/crudTools.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod'
+import type { ZodType } from 'zod'
+
+import type { Actor } from '../lib/actor.ts'
+import { MAX_FILTER_IDS } from '../lib/http.ts'
+import { MAX_PAGE_SIZE } from '../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../lib/pagination.ts'
+import type { McpToolRegistry } from '../runtime/module.ts'
+
+/**
+ * The five tools a CRM resource gets, built from the pieces its routes already
+ * carry: the same Zod bodies, the same wire mappers, the same renderer.
+ *
+ * Written once because every resource's service is the same five methods. A tool
+ * that reached for a repository, or re-derived a wire shape of its own, would be
+ * the drift `api.md` forbids: MCP mirrors the endpoints one for one, same auth,
+ * same shapes, same errors.
+ */
+
+/** What every CRM service offers. Filters differ per resource; the verbs do not. */
+export interface CrudService<View, CreateInput, UpdateInput, Filters> {
+  list(actor: Actor, filters: Filters, query: ListQueryParameters): Promise<Page<View>>
+  get(actor: Actor, id: string): Promise<View>
+  create(actor: Actor, input: CreateInput): Promise<View>
+  update(actor: Actor, id: string, changes: UpdateInput): Promise<View>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+/** An id argument. Present and non-empty; whether it exists is the service's answer. */
+export const idArg = z.string().min(1)
+
+/**
+ * A filter naming one id or a set of them, mirroring the repeated query parameter
+ * `?person_id=a&person_id=b` from `api.md`.
+ *
+ * A bare string is accepted because asking about one record is the ordinary case
+ * and an agent should not have to wrap it in an array to do so. The ceiling is the
+ * same `MAX_FILTER_IDS` the REST surface enforces, so the two refuse the same
+ * request.
+ */
+export const idSetArg = z.union([idArg, z.array(idArg).min(1).max(MAX_FILTER_IDS)])
+
+/** The same shape for a filter over a closed set of values: `?status=open&status=closed`. */
+export function enumSetArg<Value extends string>(
+  values: readonly [Value, ...Value[]],
+): ZodType<Value | Value[]> {
+  return z.union([z.enum(values), z.array(z.enum(values)).min(1).max(MAX_FILTER_IDS)])
+}
+
+/** Normalises either form of the filter above to the array a service filter takes. */
+export function toSet<Value extends string>(
+  value: Value | readonly Value[] | undefined,
+): readonly Value[] | undefined {
+  if (value === undefined) {
+    return undefined
+  }
+
+  return typeof value === 'string' ? [value] : value
+}
+
+/**
+ * Paging arguments, spread into every list tool's schema.
+ *
+ * `limit` is a number here and a string on the query line. The wire had no choice;
+ * a JSON Schema does, and a tool that declares the type it means is one an agent
+ * gets right the first time.
+ */
+export const listWindowShape = {
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_PAGE_SIZE)
+    .optional()
+    .describe(`How many records to return. 1 to ${String(MAX_PAGE_SIZE)}, default 50.`),
+  cursor: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('The next_cursor from the previous page. Opaque; do not build one.'),
+  sort: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('A documented sort field, or the same name prefixed with - for descending.'),
+}
+
+export interface ListWindowArgs {
+  readonly limit?: number | undefined
+  readonly cursor?: string | undefined
+  readonly sort?: string | undefined
+}
+
+/** The free-text filter every list carries, matching `?q=`. */
+export const termArg = z
+  .string()
+  .min(1)
+  .optional()
+  .describe('Free text. Matches the same fields the equivalent REST list matches.')
+
+/** Turns the tool's typed window into the strings `readListWindow` parses. */
+export function toListQuery(args: ListWindowArgs): ListQueryParameters {
+  return {
+    limit: args.limit === undefined ? undefined : String(args.limit),
+    sort: args.sort,
+    cursor: args.cursor,
+  }
+}
+
+/** The `{ data, next_cursor }` envelope, identical to the REST one. */
+export function pageResult<View>(
+  page: Page<View>,
+  render: (view: View) => Record<string, unknown>,
+): Record<string, unknown> {
+  return { data: page.items.map(render), next_cursor: page.nextCursor }
+}
+
+export interface CrudToolSpec<
+  View,
+  CreateInput,
+  UpdateInput,
+  Filters,
+  ListArgs extends ListWindowArgs,
+  CreateArgs,
+  UpdateArgs extends { readonly id: string },
+> {
+  /** The REST path segment, which is also the tool-name prefix: `people`. */
+  readonly resource: string
+  /** Singular, for descriptions: `person`. */
+  readonly subject: string
+  /** One line an agent reads to know what this object is for. */
+  readonly about: string
+  readonly service: CrudService<View, CreateInput, UpdateInput, Filters>
+  readonly render: (view: View) => Record<string, unknown>
+  /** Filters plus `listWindowShape`. Flat, so the published JSON Schema is one object. */
+  readonly listArgs: ZodType<ListArgs>
+  readonly toFilters: (args: ListArgs) => Filters
+  readonly createArgs: ZodType<CreateArgs>
+  readonly toCreateInput: (args: CreateArgs) => CreateInput
+  /** The update body plus a required `id`. */
+  readonly updateArgs: ZodType<UpdateArgs>
+  readonly toUpdateInput: (args: UpdateArgs) => UpdateInput
+  /**
+   * Replaces the by-id delete tool, for a resource whose REST delete takes more
+   * than an id. Pipeline stages are the only one: removing a stage may name where
+   * the records standing in it go.
+   */
+  readonly registerDelete?: (mcp: McpToolRegistry) => void
+}
+
+/** What a delete tool answers with, since the REST delete answers 204 and no body. */
+export function deleteResult(id: string): Record<string, unknown> {
+  return { id, deleted: true }
+}
+
+/**
+ * Registers `<resource>_list`, `_get`, `_create`, `_update` and `_delete`.
+ *
+ * Resource first so a client's tool list groups by object rather than by verb,
+ * which is what makes a list of roughly a hundred tools navigable.
+ */
+export function registerCrudTools<
+  View,
+  CreateInput,
+  UpdateInput,
+  Filters,
+  ListArgs extends ListWindowArgs,
+  CreateArgs,
+  UpdateArgs extends { readonly id: string },
+>(
+  mcp: McpToolRegistry,
+  spec: CrudToolSpec<View, CreateInput, UpdateInput, Filters, ListArgs, CreateArgs, UpdateArgs>,
+): void {
+  const { resource, subject, about, service, render } = spec
+
+  mcp.tool({
+    name: `${resource}_list`,
+    description: `List ${subject} records. ${about} Cursor paged. Mirrors GET /v1/${resource}.`,
+    inputSchema: spec.listArgs,
+    invoke: async (args, actor) =>
+      pageResult(await service.list(actor, spec.toFilters(args), toListQuery(args)), render),
+  })
+
+  mcp.tool({
+    name: `${resource}_get`,
+    description: `Fetch one ${subject} by id. ${about} Mirrors GET /v1/${resource}/{id}.`,
+    inputSchema: z.strictObject({ id: idArg }),
+    invoke: async ({ id }, actor) => render(await service.get(actor, id)),
+  })
+
+  mcp.tool({
+    name: `${resource}_create`,
+    description: `Create a ${subject}. ${about} Mirrors POST /v1/${resource}.`,
+    inputSchema: spec.createArgs,
+    invoke: async (args, actor) => render(await service.create(actor, spec.toCreateInput(args))),
+  })
+
+  mcp.tool({
+    name: `${resource}_update`,
+    description:
+      `Update a ${subject}. Only the fields you send change; null clears a nullable one. ` +
+      `Mirrors PATCH /v1/${resource}/{id}.`,
+    inputSchema: spec.updateArgs,
+    invoke: async (args, actor) =>
+      render(await service.update(actor, args.id, spec.toUpdateInput(args))),
+  })
+
+  if (spec.registerDelete !== undefined) {
+    spec.registerDelete(mcp)
+
+    return
+  }
+
+  mcp.tool({
+    name: `${resource}_delete`,
+    description:
+      `Delete a ${subject}. Dependent records go with it; a record something else ` +
+      `independently references refuses with a conflict. Mirrors DELETE /v1/${resource}/{id}.`,
+    inputSchema: z.strictObject({ id: idArg }),
+    invoke: async ({ id }, actor) => {
+      await service.remove(actor, id)
+
+      return deleteResult(id)
+    },
+  })
+}

package/src/modules/dashboard/attention.ts

@@ -0,0 +1,67 @@
+/**
+ * The day arithmetic behind the attention signals, with no I/O in it.
+ *
+ * Dates here are `YYYY-MM-DD` calendar days, the format `plan_items.date` and
+ * `partnerships.next_touchpoint` are stored and returned in. They compare as
+ * text because the format sorts lexicographically, so a window is a pair of
+ * string bounds rather than a range of instants.
+ *
+ * `today` is always a parameter. A function that reads the clock cannot be
+ * tested against a fixed expectation, and which day it is depends on the
+ * workspace's zone anyway (`lib/timezones.ts`).
+ */
+
+/** How long since a contact before the relationship counts as going cold. */
+export const STALE_CONTACT_DAYS = 14
+
+/** How far ahead "due soon" looks, for plan items and partnership touchpoints. */
+export const UPCOMING_DAYS = 7
+
+/**
+ * How many rows each embedded list carries when `?limit=` is absent.
+ *
+ * Smaller than the `?limit=` default every paged list uses, because this
+ * response holds seven lists rather than one and the workspace home renders
+ * four or five rows of each. The totals alongside them are exact regardless.
+ */
+export const DEFAULT_SIGNAL_LIMIT = 10
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000
+
+/**
+ * Parsed at midday so no zone offset, and no daylight-saving jump, lands the
+ * result on a neighbouring day.
+ */
+function atMidday(day: string): Date {
+  return new Date(`${day}T12:00:00Z`)
+}
+
+/** @returns `day` moved by `days`, still `YYYY-MM-DD`. */
+export function addDays(day: string, days: number): string {
+  const moved = atMidday(day)
+
+  moved.setUTCDate(moved.getUTCDate() + days)
+
+  return moved.toISOString().slice(0, 10)
+}
+
+/** @returns Whole days from `from` to `to`, negative when `to` is the earlier of the two. */
+export function daysBetween(from: string, to: string): number {
+  return Math.round((atMidday(to).getTime() - atMidday(from).getTime()) / MILLISECONDS_PER_DAY)
+}
+
+/** The last day that still counts as "due soon" from `today`. */
+export function upcomingEnd(today: string): string {
+  return addDays(today, UPCOMING_DAYS)
+}
+
+/**
+ * The first day a contact is still fresh on.
+ *
+ * A person contacted exactly `STALE_CONTACT_DAYS` ago is not yet stale: the
+ * threshold is "more than a fortnight", and treating the boundary day as late
+ * would flag somebody the day before the fortnight is up.
+ */
+export function staleContactCutoff(today: string): string {
+  return addDays(today, -STALE_CONTACT_DAYS)
+}

package/src/modules/dashboard/index.ts

@@ -0,0 +1,49 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { mountDashboardRoutes } from './routes.ts'
+import { createDashboardService } from './service.ts'
+import { registerDashboardTools } from './tools.ts'
+
+/**
+ * The workspace home: what is open, what is late, and what happened lately.
+ *
+ * It contributes no tables and calls no `context.schema`. Every row it reads
+ * belongs to another module, and a dashboard that stored its own copy would be a
+ * cache nothing invalidates.
+ *
+ * `requires` names each of those modules. Nothing here runs at registration, so
+ * the dependency is not about ordering the `register` calls: it is about a build
+ * that leaves one of them out. An assembly without `plans` would boot happily
+ * and answer this endpoint with a query against a table that has no migration.
+ */
+export function createDashboardModule(): KelpieModule {
+  return {
+    id: 'dashboard',
+    requires: [
+      'workspace',
+      'people',
+      'pipelines',
+      'deals',
+      'opportunities',
+      'raises',
+      'partnerships',
+      'plans',
+      'decisions',
+      'notes',
+      'activities',
+      'hiring',
+    ],
+    structural: true,
+
+    register(context) {
+      const service = createDashboardService({ db: context.db, now: context.now })
+
+      context.routes((router) => {
+        mountDashboardRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerDashboardTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}