@kelpie/server 0.1.0

package/src/modules/hiring/roles.ts

@@ -0,0 +1,174 @@
+import type { RoleStatus } from '@kelpie/schemas'
+
+import { changedKeys } from '../../lib/changes.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 { describeUnlink } 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_ROLE_SORT, ROLE_SORTS } from './repository.ts'
+import type { RoleFilters, RoleRecord } from './repository.ts'
+
+/**
+ * Role: an opening the workspace is hiring for.
+ *
+ * A Role holds no people and has no timeline of its own — it is not one of the
+ * `RECORD_TARGET_TYPES` a note, activity, or decision attaches to. The people
+ * are Candidates, and what happens to them is news on their own pages.
+ */
+
+export interface RolesDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/** A role as the API returns one: the stored row minus the tenancy column. */
+export type RoleView = Omit<RoleRecord, 'workspaceId'>
+
+export interface CreateRoleInput {
+  readonly title: string
+  /** Absent means open: a role is created because it is being hired for. */
+  readonly status: RoleStatus
+}
+
+export interface UpdateRoleInput {
+  readonly title?: string | undefined
+  readonly status?: RoleStatus | undefined
+}
+
+export interface RolesService {
+  list(actor: Actor, filters: RoleFilters, query: ListQueryParameters): Promise<Page<RoleView>>
+  get(actor: Actor, id: string): Promise<RoleView>
+  create(actor: Actor, input: CreateRoleInput): Promise<RoleView>
+  update(actor: Actor, id: string, changes: UpdateRoleInput): Promise<RoleView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: RoleRecord): RoleView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+function toStoredColumns(input: UpdateRoleInput): Partial<repository.RoleColumns> {
+  return {
+    ...(input.title === undefined ? {} : { title: input.title }),
+    ...(input.status === undefined ? {} : { status: input.status }),
+  }
+}
+
+export function createRolesService(dependencies: RolesDependencies): RolesService {
+  async function require(workspaceId: string, id: string): Promise<RoleRecord> {
+    const role = await repository.findRole(dependencies.db, workspaceId, id)
+
+    if (role === undefined) {
+      throw AppError.notFound('Role not found')
+    }
+
+    return role
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, ROLE_SORTS, DEFAULT_ROLE_SORT)
+      const rows = await repository.listRoles(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(toPage(rows, window, (role) => role.id), toView)
+    },
+
+    async get(actor, id) {
+      return toView(await require(requireWorkspaceId(actor), id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+      const id = dependencies.createId('role')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const created = await repository.insertRole(tx, {
+          id,
+          workspaceId,
+          title: input.title,
+          status: input.status,
+        })
+
+        events.emit('record.created', { workspaceId, objectType: 'role', recordId: id })
+
+        return toView(created)
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const columns = toStoredColumns(changes)
+      const changed = changedKeys(existing, columns)
+
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const updated = await repository.updateRole(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (updated === undefined) {
+          throw AppError.notFound('Role not found')
+        }
+
+        events.emit('record.updated', {
+          workspaceId,
+          objectType: 'role',
+          recordId: id,
+          changedFields: changed,
+        })
+
+        return toView(updated)
+      })
+    },
+
+    /**
+     * Deletes the role and, by cascade, every candidacy on it.
+     *
+     * The candidacies go through their foreign key without a service seeing
+     * them, so their interview notes are removed here first. Each affected
+     * person gets the unlink on their timeline, because a candidacy vanishing
+     * is news on the page that showed it and the role's own page is gone.
+     */
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx, events }) => {
+        const role = await require(workspaceId, id)
+        const held = await repository.listCandidatesOfRole(tx, workspaceId, id)
+
+        for (const candidacy of held) {
+          await deleteRecordsAttachedTo(tx, workspaceId, 'candidate', candidacy.id)
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'person',
+            targetId: candidacy.personId,
+            kind: 'unlinked',
+            ...describeUnlink('role', role.title),
+          })
+        }
+
+        await repository.deleteRole(tx, workspaceId, id)
+
+        events.emit('record.deleted', { workspaceId, objectType: 'role', recordId: id })
+      })
+    },
+  }
+}

package/src/modules/hiring/routes.ts

@@ -0,0 +1,257 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+import { pageBody, readIdFilter, readJsonBody, readListParameters } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type {
+  CandidateView,
+  CandidatesService,
+  CreateCandidateInput,
+  UpdateCandidateInput,
+} from './candidates.ts'
+import type { CreateRoleInput, RoleView, RolesService, UpdateRoleInput } from './roles.ts'
+import { CANDIDATE_STATUSES, INTERVIEW_STAGES, ROLE_STATUSES } from './schema.ts'
+
+/**
+ * Wire shapes for `/v1/roles` and `/v1/candidates`. Bodies are strict; an
+ * unknown field is a 422, per `api.md`.
+ */
+
+const roleShape = {
+  title: z.string().min(1),
+  status: z.enum(ROLE_STATUSES),
+}
+
+/** Only a title is required. A role exists because it is open, so that is the default. */
+export const createRoleBody = z.strictObject({
+  ...roleShape,
+  status: roleShape.status.default('open'),
+})
+
+export const updateRoleBody = z.strictObject(roleShape).partial()
+
+const candidateShape = {
+  role_id: z.string().min(1),
+  person_id: z.string().min(1),
+  status: z.enum(CANDIDATE_STATUSES),
+  interview_stage: z.enum(INTERVIEW_STAGES).nullable(),
+  referrer_person_id: z.string().min(1).nullable(),
+}
+
+/**
+ * Both ends are required; nothing else is. An absent status starts the candidacy
+ * in process, where the mockup's "Add candidate" puts one, and an absent stage
+ * lands at the first, which the service resolves along with the rule that ties
+ * the two together.
+ */
+export const createCandidateBody = z.strictObject({
+  ...candidateShape,
+  status: candidateShape.status.default('in_process'),
+  interview_stage: candidateShape.interview_stage.optional(),
+  referrer_person_id: candidateShape.referrer_person_id.default(null),
+})
+
+/** Neither end. Repointing a candidacy is a delete and a create, as with a Position. */
+export const updateCandidateBody = z
+  .strictObject({
+    status: candidateShape.status,
+    interview_stage: candidateShape.interview_stage,
+    referrer_person_id: candidateShape.referrer_person_id,
+  })
+  .partial()
+
+export interface HiringRoutesDependencies extends CredentialDependencies {
+  readonly roles: RolesService
+  readonly candidates: CandidatesService
+}
+
+/**
+ * An enum filter, validated rather than matched against nothing.
+ *
+ * `readIdFilter` handles the repeat-to-name-a-set shape; what it cannot know is
+ * which values exist. An unknown one is a `422` here for the same reason it is
+ * in a body: silently answering "no records" would report a typo as an empty
+ * pipeline.
+ */
+function readEnumFilter<Value extends string>(
+  context: Context,
+  name: string,
+  allowed: readonly Value[],
+): readonly Value[] | undefined {
+  const values = readIdFilter(context, name)
+
+  if (values === undefined) {
+    return undefined
+  }
+
+  const unknown = values.filter((value) => !allowed.includes(value as Value))
+
+  if (unknown.length > 0) {
+    throw AppError.validationFailed(`"${name}" does not take ${unknown.join(', ')}`, [
+      { field: name, message: `Expected one of ${allowed.join(', ')}` },
+    ])
+  }
+
+  return values as readonly Value[]
+}
+
+export function toCreateRoleInput(body: z.infer<typeof createRoleBody>): CreateRoleInput {
+  return { title: body.title, status: body.status }
+}
+
+export function toUpdateRoleInput(body: z.infer<typeof updateRoleBody>): UpdateRoleInput {
+  return {
+    ...(body.title === undefined ? {} : { title: body.title }),
+    ...(body.status === undefined ? {} : { status: body.status }),
+  }
+}
+
+export function roleResponse(role: RoleView): Record<string, unknown> {
+  return {
+    id: role.id,
+    title: role.title,
+    status: role.status,
+    created_at: role.createdAt.toISOString(),
+    updated_at: role.updatedAt.toISOString(),
+  }
+}
+
+export function toCreateCandidateInput(
+  body: z.infer<typeof createCandidateBody>,
+): CreateCandidateInput {
+  return {
+    roleId: body.role_id,
+    personId: body.person_id,
+    status: body.status,
+    interviewStage: body.interview_stage,
+    referrerPersonId: body.referrer_person_id,
+  }
+}
+
+export function toUpdateCandidateInput(
+  body: z.infer<typeof updateCandidateBody>,
+): UpdateCandidateInput {
+  return {
+    ...(body.status === undefined ? {} : { status: body.status }),
+    ...(body.interview_stage === undefined ? {} : { interviewStage: body.interview_stage }),
+    ...(body.referrer_person_id === undefined
+      ? {}
+      : { referrerPersonId: body.referrer_person_id }),
+  }
+}
+
+export function candidateResponse(candidate: CandidateView): Record<string, unknown> {
+  return {
+    id: candidate.id,
+    role_id: candidate.roleId,
+    person_id: candidate.personId,
+    status: candidate.status,
+    interview_stage: candidate.interviewStage,
+    referrer_person_id: candidate.referrerPersonId,
+    created_at: candidate.createdAt.toISOString(),
+    updated_at: candidate.updatedAt.toISOString(),
+  }
+}
+
+export function mountHiringRoutes(router: Hono, dependencies: HiringRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/roles', async (context) => {
+    const page = await dependencies.roles.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        statuses: readEnumFilter(context, 'status', ROLE_STATUSES),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, roleResponse))
+  })
+
+  router.post('/roles', async (context) => {
+    const body = await readJsonBody(context, createRoleBody)
+    const role = await dependencies.roles.create(
+      await requireActor(context),
+      toCreateRoleInput(body),
+    )
+
+    return context.json(roleResponse(role), 201)
+  })
+
+  router.get('/roles/:id', async (context) => {
+    const role = await dependencies.roles.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(roleResponse(role))
+  })
+
+  router.patch('/roles/:id', async (context) => {
+    const body = await readJsonBody(context, updateRoleBody)
+    const role = await dependencies.roles.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateRoleInput(body),
+    )
+
+    return context.json(roleResponse(role))
+  })
+
+  router.delete('/roles/:id', async (context) => {
+    await dependencies.roles.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  router.get('/candidates', async (context) => {
+    const page = await dependencies.candidates.list(
+      await requireActor(context),
+      {
+        roleIds: readIdFilter(context, 'role_id'),
+        personIds: readIdFilter(context, 'person_id'),
+        statuses: readEnumFilter(context, 'status', CANDIDATE_STATUSES),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, candidateResponse))
+  })
+
+  router.post('/candidates', async (context) => {
+    const body = await readJsonBody(context, createCandidateBody)
+    const candidate = await dependencies.candidates.create(
+      await requireActor(context),
+      toCreateCandidateInput(body),
+    )
+
+    return context.json(candidateResponse(candidate), 201)
+  })
+
+  router.get('/candidates/:id', async (context) => {
+    const candidate = await dependencies.candidates.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(candidateResponse(candidate))
+  })
+
+  router.patch('/candidates/:id', async (context) => {
+    const body = await readJsonBody(context, updateCandidateBody)
+    const candidate = await dependencies.candidates.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateCandidateInput(body),
+    )
+
+    return context.json(candidateResponse(candidate))
+  })
+
+  router.delete('/candidates/:id', async (context) => {
+    await dependencies.candidates.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/hiring/schema.ts

@@ -0,0 +1,93 @@
+import { CANDIDATE_STATUSES, INTERVIEW_STAGES, ROLE_STATUSES } from '@kelpie/schemas'
+import { sql } from 'drizzle-orm'
+import { check, index, pgTable, text, unique } from 'drizzle-orm/pg-core'
+
+import {
+  checkOneOf,
+  createdAt,
+  oneOf,
+  primaryId,
+  searchVector,
+  updatedAt,
+} from '../../lib/columns.ts'
+import type { SearchVectorPart } from '../../lib/columns.ts'
+import { people } from '../people/schema.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * The value sets come from `@kelpie/schemas`, so these check constraints, the
+ * routes' Zod enums, and the browser's dropdowns are one list rather than three
+ * copies. Re-exported because `service.ts` and `routes.ts` read them from here,
+ * and the tables they constrain are the reason they matter.
+ */
+export {
+  CANDIDATE_STATUSES,
+  CANDIDATE_STATUS_LABELS,
+  FIRST_INTERVIEW_STAGE,
+  IN_PROCESS,
+  INTERVIEW_STAGES,
+  INTERVIEW_STAGE_LABELS,
+  ROLE_STATUSES,
+} from '@kelpie/schemas'
+export type { CandidateStatus, InterviewStage, RoleStatus } from '@kelpie/schemas'
+
+/** An opening the workspace is hiring for. Candidates attach here, never to Person. */
+export const roles = pgTable(
+  'roles',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    title: text('title').notNull(),
+    status: text('status').notNull(),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    searchVector: searchVector((): readonly SearchVectorPart[] => [{ column: roles.title, weight: 'A' }]),
+  },
+  (table) => [
+    index('roles_workspace_idx').on(table.workspaceId),
+    index('roles_search_idx').using('gin', table.searchVector),
+    checkOneOf('roles_status_check', table.status, ROLE_STATUSES),
+  ],
+)
+
+/**
+ * The Person-to-Role link. Pipeline state lives here.
+ *
+ * `interview_stage` is null unless `status` is `in_process`. That rule is
+ * enforced in the service layer, mirroring the mockup's `candidatePatchForStatus`,
+ * because a check constraint cannot express it without pinning the transition
+ * order too.
+ */
+export const candidates = pgTable(
+  'candidates',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    roleId: text('role_id')
+      .notNull()
+      .references(() => roles.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'cascade' }),
+    status: text('status').notNull(),
+    interviewStage: text('interview_stage'),
+    referrerPersonId: text('referrer_person_id').references(() => people.id, {
+      onDelete: 'restrict',
+    }),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    unique('candidates_role_person_key').on(table.roleId, table.personId),
+    index('candidates_workspace_idx').on(table.workspaceId),
+    checkOneOf('candidates_status_check', table.status, CANDIDATE_STATUSES),
+    check(
+      'candidates_interview_stage_check',
+      sql`${table.interviewStage} is null or ${oneOf('candidates_interview_stage_check', table.interviewStage, INTERVIEW_STAGES)}`,
+    ),
+  ],
+)

package/src/modules/hiring/tools.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { enumSetArg, idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import type { CandidatesService } from './candidates.ts'
+import type { RolesService } from './roles.ts'
+import {
+  candidateResponse,
+  createCandidateBody,
+  createRoleBody,
+  roleResponse,
+  toCreateCandidateInput,
+  toCreateRoleInput,
+  toUpdateCandidateInput,
+  toUpdateRoleInput,
+  updateCandidateBody,
+  updateRoleBody,
+} from './routes.ts'
+import { CANDIDATE_STATUSES, ROLE_STATUSES } from './schema.ts'
+
+/** `roles_*` and `candidates_*`. Same schemas and mappers as `/v1/roles` and `/v1/candidates`. */
+
+const roleListArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg,
+  status: enumSetArg(ROLE_STATUSES).optional().describe('open, closed, or both.'),
+})
+
+const candidateListArgs = z.strictObject({
+  ...listWindowShape,
+  role_id: idSetArg.optional().describe('One role\'s pipeline.'),
+  person_id: idSetArg.optional().describe('Every role these people are up for.'),
+  status: enumSetArg(CANDIDATE_STATUSES).optional().describe('The candidacy\'s pipeline state.'),
+})
+
+export function registerHiringTools(
+  mcp: McpToolRegistry,
+  services: { readonly roles: RolesService; readonly candidates: CandidatesService },
+): void {
+  registerCrudTools(mcp, {
+    resource: 'roles',
+    subject: 'role',
+    about: 'An opening this workspace is hiring for. Candidates attach to a role, never to a person.',
+    service: services.roles,
+    render: roleResponse,
+    listArgs: roleListArgs,
+    toFilters: (args) => ({ term: args.q, statuses: toSet(args.status) }),
+    createArgs: createRoleBody,
+    toCreateInput: toCreateRoleInput,
+    updateArgs: updateRoleBody.extend({ id: idArg }),
+    toUpdateInput: toUpdateRoleInput,
+  })
+
+  registerCrudTools(mcp, {
+    resource: 'candidates',
+    subject: 'candidate',
+    about:
+      'One person\'s candidacy for one role: status, interview stage while in process, ' +
+      'and who referred them. Interview notes attach here, not to the person.',
+    service: services.candidates,
+    render: candidateResponse,
+    listArgs: candidateListArgs,
+    toFilters: (args) => ({
+      roleIds: toSet(args.role_id),
+      personIds: toSet(args.person_id),
+      statuses: toSet(args.status),
+    }),
+    createArgs: createCandidateBody,
+    toCreateInput: toCreateCandidateInput,
+    updateArgs: updateCandidateBody.extend({ id: idArg }),
+    toUpdateInput: toUpdateCandidateInput,
+  })
+}