@kelpie/server 0.1.0

package/src/modules/hiring/candidates.ts

@@ -0,0 +1,391 @@
+import { CANDIDATE_STATUS_LABELS, INTERVIEW_STAGE_LABELS } from '@kelpie/schemas'
+import type { CandidateStatus, InterviewStage } from '@kelpie/schemas'
+
+import { changedKeys } from '../../lib/changes.ts'
+import { UNIQUE_VIOLATION, postgresErrorCode } from '../../lib/database.ts'
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import { describeLink, describeUnlink, describeUpdate } from '../activities/wording.ts'
+import type { FieldLabels } from '../activities/wording.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_CANDIDATE_SORT, CANDIDATE_SORTS } from './repository.ts'
+import type { CandidateFilters, CandidateRecord } from './repository.ts'
+import { FIRST_INTERVIEW_STAGE, IN_PROCESS } from './schema.ts'
+
+/**
+ * Candidate: the Person↔Role link, and the only place hiring pipeline state
+ * lives. A bare set of hiring fields on Person would force one pipeline per
+ * person, which is wrong for anyone considered for two roles.
+ *
+ * A candidacy has no timeline of its own that anything reads. What happens to it
+ * is filed on the **person's** timeline, which is where the mockup's own seeded
+ * hiring activity sits (`targetType: "person"` in `mockups/src/data/seed.ts`)
+ * and the only page that shows it. Notes are the other way round: an interview
+ * note is about this candidacy, not about the person in general, so it attaches
+ * here.
+ */
+
+export interface CandidatesDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/** What a changed column is called on a timeline. */
+const CANDIDATE_FIELD_LABELS: FieldLabels = {
+  status: 'Candidate status',
+  interviewStage: 'Interview stage',
+  referrerPersonId: 'Referrer',
+}
+
+/** A candidate as the API returns one: the stored row minus the tenancy column. */
+export type CandidateView = Omit<CandidateRecord, 'workspaceId'>
+
+export interface CreateCandidateInput {
+  readonly roleId: string
+  readonly personId: string
+  /** Absent means in process, where the mockup's "Add candidate" starts one. */
+  readonly status: CandidateStatus
+  /** Absent means the first stage while in process, and nothing otherwise. */
+  readonly interviewStage: InterviewStage | null | undefined
+  readonly referrerPersonId: string | null
+}
+
+/**
+ * PATCH semantics: an absent field is left alone, and null clears a nullable one.
+ *
+ * Neither end is here. Repointing a candidacy at a different person or role is a
+ * delete and a create, the rule Position already follows.
+ */
+export interface UpdateCandidateInput {
+  readonly status?: CandidateStatus | undefined
+  readonly interviewStage?: InterviewStage | null | undefined
+  readonly referrerPersonId?: string | null | undefined
+}
+
+export interface CandidatesService {
+  list(
+    actor: Actor,
+    filters: CandidateFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<CandidateView>>
+  get(actor: Actor, id: string): Promise<CandidateView>
+  create(actor: Actor, input: CreateCandidateInput): Promise<CandidateView>
+  update(actor: Actor, id: string, changes: UpdateCandidateInput): Promise<CandidateView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: CandidateRecord): CandidateView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+function duplicateCandidacy(): AppError {
+  return AppError.conflict('That person is already a candidate for that role', [
+    { field: 'person_id', message: 'Already a candidate for this role' },
+  ])
+}
+
+/**
+ * The interview stage a candidacy carries once a write lands, mirroring the
+ * mockup's `candidatePatchForStatus`.
+ *
+ * Leaving `in_process` clears the stage. That is normalisation of a dependent
+ * column rather than a caller's value being dropped: a stage on a passed
+ * candidate would claim they are still being interviewed. A caller who names a
+ * stage that contradicts the status is refused instead, in `requireStageFits`.
+ *
+ * Pure and exported so the rule can be read and tested without a database.
+ */
+export function interviewStageAfter(
+  status: CandidateStatus,
+  requested: InterviewStage | null | undefined,
+  current: InterviewStage | null,
+): InterviewStage | null {
+  if (status !== IN_PROCESS) {
+    return null
+  }
+
+  return requested ?? current ?? FIRST_INTERVIEW_STAGE
+}
+
+/**
+ * @throws AppError 422 when the stage and the status cannot both be true. An
+ *   unknown enum is a 422 at the boundary per `api.md`, and so is a known one
+ *   that contradicts the record it is being written to.
+ */
+function requireStageFits(
+  status: CandidateStatus,
+  requested: InterviewStage | null | undefined,
+): void {
+  if (requested === undefined) {
+    return
+  }
+
+  if (status !== IN_PROCESS && requested !== null) {
+    throw AppError.validationFailed('Only a candidate in process has an interview stage', [
+      { field: 'interview_stage', message: `Not while the status is ${status}` },
+    ])
+  }
+
+  if (status === IN_PROCESS && requested === null) {
+    throw AppError.validationFailed('A candidate in process is always at some stage', [
+      { field: 'interview_stage', message: 'Expected a stage' },
+    ])
+  }
+}
+
+/**
+ * The values a timeline prints, from the values a column stores.
+ *
+ * `describeUpdate` renders `old → new` out of whatever it is handed, and a raw
+ * enum slug or a person id there reads as noise. This is the one place that
+ * turns them into what the mockup writes: "In process → Nurture", not
+ * "in_process → nurture".
+ */
+function readable(
+  columns: Partial<repository.CandidateColumns>,
+  names: ReadonlyMap<string, string>,
+): Record<string, unknown> {
+  const referrerId = columns.referrerPersonId
+
+  return {
+    ...(columns.status === undefined
+      ? {}
+      : { status: CANDIDATE_STATUS_LABELS[columns.status as CandidateStatus] ?? columns.status }),
+    ...(columns.interviewStage === undefined
+      ? {}
+      : {
+          interviewStage:
+            columns.interviewStage === null
+              ? null
+              : (INTERVIEW_STAGE_LABELS[columns.interviewStage as InterviewStage] ??
+                columns.interviewStage),
+        }),
+    ...(referrerId === undefined
+      ? {}
+      : { referrerPersonId: referrerId === null ? null : (names.get(referrerId) ?? referrerId) }),
+  }
+}
+
+export function createCandidatesService(dependencies: CandidatesDependencies): CandidatesService {
+  async function require(workspaceId: string, id: string): Promise<CandidateRecord> {
+    const candidate = await repository.findCandidate(dependencies.db, workspaceId, id)
+
+    if (candidate === undefined) {
+      throw AppError.notFound('Candidate not found')
+    }
+
+    return candidate
+  }
+
+  async function requireRole(workspaceId: string, roleId: string): Promise<string> {
+    const role = await repository.findRole(dependencies.db, workspaceId, roleId)
+
+    if (role === undefined) {
+      throw AppError.notFound('Role not found')
+    }
+
+    return role.title
+  }
+
+  /**
+   * Every named person must be in the caller's workspace. The foreign keys are
+   * global, so this is what makes the tenancy boundary hold, and a person on the
+   * far side of it reports as missing rather than as forbidden, per `api.md`.
+   *
+   * @returns Their names, for the timeline rows that name them.
+   */
+  async function requirePeople(
+    workspaceId: string,
+    personIds: readonly string[],
+  ): Promise<ReadonlyMap<string, string>> {
+    const wanted = [...new Set(personIds)]
+    const named = await repository.findPeopleNamed(dependencies.db, workspaceId, wanted)
+    const missing = wanted.filter((id) => !named.has(id))
+
+    if (missing.length > 0) {
+      throw AppError.notFound('Person not found')
+    }
+
+    return named
+  }
+
+  /** A referral is one person vouching for another, so it cannot point back at the candidate. */
+  function requireReferrerIsSomeoneElse(personId: string, referrerPersonId: string | null): void {
+    if (referrerPersonId === personId) {
+      throw AppError.validationFailed('A candidate cannot be their own referrer', [
+        { field: 'referrer_person_id', message: 'Expected a different person' },
+      ])
+    }
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, CANDIDATE_SORTS, DEFAULT_CANDIDATE_SORT)
+      const rows = await repository.listCandidates(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(toPage(rows, window, (candidate) => candidate.id), toView)
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      requireStageFits(input.status, input.interviewStage)
+      requireReferrerIsSomeoneElse(input.personId, input.referrerPersonId)
+
+      const roleTitle = await requireRole(workspaceId, input.roleId)
+
+      await requirePeople(
+        workspaceId,
+        input.referrerPersonId === null ? [input.personId] : [input.personId, input.referrerPersonId],
+      )
+
+      const id = dependencies.createId('candidate')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        let created: CandidateRecord
+
+        try {
+          created = await repository.insertCandidate(tx, {
+            id,
+            workspaceId,
+            roleId: input.roleId,
+            personId: input.personId,
+            status: input.status,
+            interviewStage: interviewStageAfter(input.status, input.interviewStage, null),
+            referrerPersonId: input.referrerPersonId,
+          })
+        } catch (error: unknown) {
+          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+            throw duplicateCandidacy()
+          }
+
+          throw error
+        }
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: input.personId,
+          kind: 'linked',
+          ...describeLink('role', roleTitle),
+        })
+
+        events.emit('record.created', { workspaceId, objectType: 'candidate', recordId: id })
+
+        return toView(created)
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const status = changes.status ?? (existing.status as CandidateStatus)
+
+      requireStageFits(status, changes.interviewStage)
+
+      if (changes.referrerPersonId !== undefined) {
+        requireReferrerIsSomeoneElse(existing.personId, changes.referrerPersonId)
+      }
+
+      // Both sides of a referrer change, so the timeline can name whoever is
+      // leaving the field as well as whoever is arriving in it.
+      const named = await requirePeople(
+        workspaceId,
+        [changes.referrerPersonId, existing.referrerPersonId].filter(
+          (personId): personId is string => typeof personId === 'string',
+        ),
+      )
+
+      const columns: Partial<repository.CandidateColumns> = {
+        ...(changes.status === undefined ? {} : { status: changes.status }),
+        // Always recomputed: a status leaving `in_process` clears the stage even
+        // when the request said nothing about it.
+        interviewStage: interviewStageAfter(
+          status,
+          changes.interviewStage,
+          existing.interviewStage as InterviewStage | null,
+        ),
+        ...(changes.referrerPersonId === undefined
+          ? {}
+          : { referrerPersonId: changes.referrerPersonId }),
+      }
+      const changed = changedKeys(existing, columns)
+
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const updated = await repository.updateCandidate(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (updated === undefined) {
+          throw AppError.notFound('Candidate not found')
+        }
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: existing.personId,
+          kind: 'updated',
+          ...describeUpdate(
+            changed,
+            CANDIDATE_FIELD_LABELS,
+            readable(existing, named),
+            readable(columns, named),
+          ),
+        })
+
+        events.emit('record.updated', {
+          workspaceId,
+          objectType: 'candidate',
+          recordId: id,
+          changedFields: changed,
+        })
+
+        return toView(updated)
+      })
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx, events }) => {
+        const candidate = await require(workspaceId, id)
+        const roleTitle = await requireRole(workspaceId, candidate.roleId)
+
+        // Interview notes and their `note_added` rows carry no foreign key to
+        // the candidacy, so nothing in the database removes them.
+        await deleteRecordsAttachedTo(tx, workspaceId, 'candidate', id)
+        await repository.deleteCandidate(tx, workspaceId, id)
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'person',
+          targetId: candidate.personId,
+          kind: 'unlinked',
+          ...describeUnlink('role', roleTitle),
+        })
+
+        events.emit('record.deleted', { workspaceId, objectType: 'candidate', recordId: id })
+      })
+    },
+  }
+}

package/src/modules/hiring/index.ts

@@ -0,0 +1,55 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { createCandidatesService } from './candidates.ts'
+import { createRolesService } from './roles.ts'
+import { mountHiringRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { registerHiringTools } from './tools.ts'
+
+/**
+ * Hiring: the roles a workspace is filling, and the people up for them.
+ *
+ * Two resources rather than one, because they have different lives. A Role
+ * outlives the candidacies on it, and a Candidate is the link that carries the
+ * pipeline state — a shape Person cannot hold, since one person can be in
+ * process for one role and in the nurture pile for another.
+ *
+ * Requires `people` because both ends of a candidacy are checked against the
+ * caller's workspace before it is linked, and `activities` because every write
+ * leaves its entry on the person's timeline in the same transaction.
+ */
+export function createHiringModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'hiring',
+    requires: ['people', 'activities'],
+
+    register(context) {
+      const recordActivity = createActivityRecorder({
+        createId: context.createId,
+        now: context.now,
+      })
+      const services = {
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity,
+      }
+
+      context.schema(schema, migrationsDirectory)
+
+      const hiring = {
+        roles: createRolesService(services),
+        candidates: createCandidatesService(services),
+      }
+
+      context.routes((router) => {
+        mountHiringRoutes(router, { db: context.db, now: context.now, ...hiring })
+      })
+
+      registerHiringTools(context.mcp, hiring)
+
+      return Promise.resolve()
+    },
+  }
+}

package/src/modules/hiring/repository.ts

@@ -0,0 +1,244 @@
+import { and, eq, ilike, inArray } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import { containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { people } from '../people/schema.ts'
+import { candidates, roles } from './schema.ts'
+
+export type RoleRecord = typeof roles.$inferSelect
+export type CandidateRecord = typeof candidates.$inferSelect
+
+/** The writable column shapes. Services build these; nothing else knows the column names. */
+export type RoleColumns = typeof roles.$inferInsert
+export type CandidateColumns = typeof candidates.$inferInsert
+
+export const ROLE_SORTS: SortableFields<RoleRecord> = {
+  title: textSort(roles.title, (role) => role.title),
+  created_at: timestampSort(roles.createdAt, (role) => role.createdAt),
+  updated_at: timestampSort(roles.updatedAt, (role) => role.updatedAt),
+}
+
+export const DEFAULT_ROLE_SORT = '-created_at'
+
+export interface RoleFilters {
+  /** `?q=`: the title, which is all the mockup's filter box matches on a role. */
+  readonly term?: string | undefined
+  /** `?status=`, repeatable: open, closed, or both. */
+  readonly statuses?: readonly string[] | undefined
+}
+
+function roleConditionsFor(workspaceId: string, filters: RoleFilters): (SQL | undefined)[] {
+  return [
+    eq(roles.workspaceId, workspaceId),
+    filters.term === undefined ? undefined : ilike(roles.title, containsPattern(filters.term)),
+    filters.statuses === undefined ? undefined : inArray(roles.status, filters.statuses),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listRoles(
+  db: Queryable,
+  workspaceId: string,
+  filters: RoleFilters,
+  window: ListWindow<RoleRecord>,
+): Promise<RoleRecord[]> {
+  return db
+    .select()
+    .from(roles)
+    .where(and(...roleConditionsFor(workspaceId, filters), keysetCondition(window, roles.id)))
+    .orderBy(...orderByWindow(window, roles.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findRole(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<RoleRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(roles)
+    .where(and(eq(roles.workspaceId, workspaceId), eq(roles.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertRole(db: Queryable, values: RoleColumns): Promise<RoleRecord> {
+  const [created] = await db.insert(roles).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting role ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateRole(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<RoleColumns>,
+): Promise<RoleRecord | undefined> {
+  const [updated] = await db
+    .update(roles)
+    .set(changes)
+    .where(and(eq(roles.workspaceId, workspaceId), eq(roles.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteRole(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(roles)
+    .where(and(eq(roles.workspaceId, workspaceId), eq(roles.id, id)))
+    .returning({ id: roles.id })
+
+  return deleted.length
+}
+
+/**
+ * No `title` sort and no `?q=`. A candidacy holds no text of its own; the name a
+ * reader sorts or searches by belongs to the person on the far side of the link.
+ */
+export const CANDIDATE_SORTS: SortableFields<CandidateRecord> = {
+  created_at: timestampSort(candidates.createdAt, (candidate) => candidate.createdAt),
+  updated_at: timestampSort(candidates.updatedAt, (candidate) => candidate.updatedAt),
+}
+
+export const DEFAULT_CANDIDATE_SORT = '-created_at'
+
+export interface CandidateFilters {
+  /** `?role_id=`, repeatable: one role's pipeline, or a page of roles' counts. */
+  readonly roleIds?: readonly string[] | undefined
+  /** `?person_id=`, repeatable: every role a person is up for. */
+  readonly personIds?: readonly string[] | undefined
+  /** `?status=`, repeatable: the pipeline state this record exists to hold. */
+  readonly statuses?: readonly string[] | undefined
+}
+
+function candidateConditionsFor(
+  workspaceId: string,
+  filters: CandidateFilters,
+): (SQL | undefined)[] {
+  return [
+    eq(candidates.workspaceId, workspaceId),
+    filters.roleIds === undefined ? undefined : inArray(candidates.roleId, filters.roleIds),
+    filters.personIds === undefined ? undefined : inArray(candidates.personId, filters.personIds),
+    filters.statuses === undefined ? undefined : inArray(candidates.status, filters.statuses),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listCandidates(
+  db: Queryable,
+  workspaceId: string,
+  filters: CandidateFilters,
+  window: ListWindow<CandidateRecord>,
+): Promise<CandidateRecord[]> {
+  return db
+    .select()
+    .from(candidates)
+    .where(
+      and(
+        ...candidateConditionsFor(workspaceId, filters),
+        keysetCondition(window, candidates.id),
+      ),
+    )
+    .orderBy(...orderByWindow(window, candidates.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findCandidate(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<CandidateRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(candidates)
+    .where(and(eq(candidates.workspaceId, workspaceId), eq(candidates.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/** Every candidacy on one role, for the cascade its delete performs. */
+export function listCandidatesOfRole(
+  db: Queryable,
+  workspaceId: string,
+  roleId: string,
+): Promise<CandidateRecord[]> {
+  return db
+    .select()
+    .from(candidates)
+    .where(and(eq(candidates.workspaceId, workspaceId), eq(candidates.roleId, roleId)))
+}
+
+export async function insertCandidate(
+  db: Queryable,
+  values: CandidateColumns,
+): Promise<CandidateRecord> {
+  const [created] = await db.insert(candidates).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting candidate ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateCandidate(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<CandidateColumns>,
+): Promise<CandidateRecord | undefined> {
+  const [updated] = await db
+    .update(candidates)
+    .set(changes)
+    .where(and(eq(candidates.workspaceId, workspaceId), eq(candidates.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteCandidate(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(candidates)
+    .where(and(eq(candidates.workspaceId, workspaceId), eq(candidates.id, id)))
+    .returning({ id: candidates.id })
+
+  return deleted.length
+}
+
+/**
+ * The names of these people in this workspace, keyed by id. An id missing from
+ * the map does not exist here, which is how `person_id` and `referrer_person_id`
+ * are validated. Reads the `people` *table*, per the cross-relation rule in
+ * `architecture.md`.
+ */
+export async function findPeopleNamed(
+  db: Queryable,
+  workspaceId: string,
+  personIds: readonly string[],
+): Promise<ReadonlyMap<string, string>> {
+  if (personIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .select({ id: people.id, name: people.name })
+    .from(people)
+    .where(and(eq(people.workspaceId, workspaceId), inArray(people.id, personIds)))
+
+  return new Map(rows.map((row) => [row.id, row.name]))
+}