@kelpie/server 0.1.0

package/src/modules/handbook/service.ts

@@ -0,0 +1,399 @@
+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 { Transaction, TransactionScope } from '../../runtime/transaction.ts'
+import type { Actor } from '../auth/actor.ts'
+import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_HANDBOOK_PAGE_SORT, HANDBOOK_PAGE_SORTS } from './repository.ts'
+import type { HandbookPageFilters, HandbookPageRecord } from './repository.ts'
+import { slugFromTitle, uniqueSlug } from './slugs.ts'
+import { MAX_DEPTH, childrenOf, depthOf, descendantIds, placeAt, rejectMove } from './tree.ts'
+import type { MoveRejection } from './tree.ts'
+
+/**
+ * The handbook: nested markdown pages, read by people in a sidebar and by agents
+ * over the same endpoints.
+ *
+ * This service owns the two rules the schema cannot hold. Depth and the
+ * no-descendant-cycles rule are checked here because a self-referencing foreign
+ * key expresses the shape of a tree and nothing about its bounds. Sibling order
+ * is kept contiguous from 0 for the same reason a pipeline's is: it is what lets
+ * a PATCHed `sort_order` mean "position in the sidebar" rather than an opaque
+ * number a client has to guess a gap in.
+ */
+
+export interface HandbookDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+}
+
+/** A page as the API returns one: the stored row minus the tenancy column. */
+export type HandbookPageView = Omit<HandbookPageRecord, 'workspaceId'>
+
+export interface CreateHandbookPageInput {
+  readonly title: string
+  /** Absent means empty. A page is created before it is written, which is the point of "Add subpage". */
+  readonly body: string
+  /** Absent means derived from the title, with a numeric suffix if that is taken. */
+  readonly slug: string | undefined
+  /** Null means top level. */
+  readonly parentId: string | null
+}
+
+/**
+ * PATCH semantics: an absent field is left alone.
+ *
+ * `parentId` and `sortOrder` are the move; `title`, `body` and `slug` are the
+ * edit. A request may carry both, and the two are applied in that order so the
+ * page ends up where it was put with what it was given.
+ */
+export interface UpdateHandbookPageInput {
+  readonly title?: string | undefined
+  readonly body?: string | undefined
+  readonly slug?: string | undefined
+  /** Null moves the page to the top level. */
+  readonly parentId?: string | null | undefined
+  /** The page's new position among its siblings, 0-based. */
+  readonly sortOrder?: number | undefined
+}
+
+export interface HandbookService {
+  list(
+    actor: Actor,
+    filters: HandbookPageFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<HandbookPageView>>
+  get(actor: Actor, id: string): Promise<HandbookPageView>
+  create(actor: Actor, input: CreateHandbookPageInput): Promise<HandbookPageView>
+  update(actor: Actor, id: string, changes: UpdateHandbookPageInput): Promise<HandbookPageView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: HandbookPageRecord): HandbookPageView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+/** The 422 a refused move produces. Each rejection is a different mistake, so each says something different. */
+function moveRefused(rejection: MoveRejection): AppError {
+  const messages: Readonly<Record<MoveRejection, string>> = {
+    self: 'A page cannot be nested under itself',
+    descendant: 'A page cannot be nested under one of its own subpages',
+    missing_parent: 'That parent page is not in this workspace',
+    too_deep: `The handbook nests ${String(MAX_DEPTH + 1)} levels deep at most`,
+  }
+
+  return AppError.validationFailed(messages[rejection], [
+    { field: 'parent_id', message: messages[rejection] },
+  ])
+}
+
+function duplicateSlug(): AppError {
+  return AppError.conflict('A handbook page in this workspace already uses that address', [
+    { field: 'slug', message: 'Already in use' },
+  ])
+}
+
+export function createHandbookService(dependencies: HandbookDependencies): HandbookService {
+  async function require(workspaceId: string, id: string): Promise<HandbookPageRecord> {
+    const page = await repository.findPage(dependencies.db, workspaceId, id)
+
+    // A page in another workspace is indistinguishable from one that never
+    // existed, per `api.md`.
+    if (page === undefined) {
+      throw AppError.notFound('Handbook page not found')
+    }
+
+    return page
+  }
+
+  /**
+   * Writes a sibling set back as positions 0..n-1, touching only the rows that
+   * moved, and re-parenting `reparented` if it is one of them.
+   *
+   * `updated_at` and `updated_by` are deliberately not written. They say who last
+   * wrote the page, which is the line the reader sees under its title, and a page
+   * that shifted down one because a neighbour was dragged above it was not
+   * written by anybody.
+   */
+  async function renumber(
+    tx: Transaction,
+    workspaceId: string,
+    order: readonly HandbookPageRecord[],
+    reparented: { readonly id: string; readonly parentId: string | null } | undefined,
+  ): Promise<void> {
+    for (const [index, page] of order.entries()) {
+      const movesParent = reparented !== undefined && reparented.id === page.id
+      const movesOrder = page.sortOrder !== index
+
+      if (!movesParent && !movesOrder) {
+        continue
+      }
+
+      await repository.updatePage(tx, workspaceId, page.id, {
+        ...(movesParent ? { parentId: reparented.parentId } : {}),
+        sortOrder: index,
+      })
+    }
+  }
+
+  /**
+   * Applies a move, and reports which fields it changed.
+   *
+   * The page is lifted out of its sibling set and dropped into the target one at
+   * `position`, then both sets are renumbered. When the parent does not change
+   * there is only one set, and lifting then re-inserting is what turns a
+   * `sort_order` of 2 into "third among your siblings" rather than a raw column
+   * write that could leave two pages sharing a position.
+   *
+   * @param position Absent leaves the page where it sits, which for a re-nest
+   *   means the end of its new sibling set: there is no position to keep.
+   */
+  async function move(
+    tx: Transaction,
+    workspaceId: string,
+    page: HandbookPageRecord,
+    parentId: string | null,
+    position: number | undefined,
+  ): Promise<readonly string[]> {
+    const all = await repository.listAllPages(tx, workspaceId)
+    const changesParent = parentId !== page.parentId
+
+    if (changesParent) {
+      const rejection = rejectMove(all, page.id, parentId)
+
+      if (rejection !== undefined) {
+        throw moveRefused(rejection)
+      }
+    }
+
+    const siblings = childrenOf(all, parentId).filter((sibling) => sibling.id !== page.id)
+    const held = childrenOf(all, page.parentId).findIndex((sibling) => sibling.id === page.id)
+
+    await renumber(
+      tx,
+      workspaceId,
+      placeAt(siblings, page, position ?? (changesParent ? siblings.length : held)),
+      changesParent ? { id: page.id, parentId } : undefined,
+    )
+
+    if (changesParent) {
+      await renumber(tx, workspaceId, siblingsOf(all, page), undefined)
+    }
+
+    const moved = await repository.findPage(tx, workspaceId, page.id)
+
+    if (moved === undefined) {
+      throw AppError.notFound('Handbook page not found')
+    }
+
+    return [
+      ...(changesParent ? ['parentId'] : []),
+      ...(moved.sortOrder === page.sortOrder ? [] : ['sortOrder']),
+    ]
+  }
+
+  /** The set a page is leaving, without the page. Renumbered so it stays contiguous from 0. */
+  function siblingsOf(
+    all: readonly HandbookPageRecord[],
+    page: HandbookPageRecord,
+  ): HandbookPageRecord[] {
+    return childrenOf(all, page.parentId).filter((sibling) => sibling.id !== page.id)
+  }
+
+  /**
+   * The edit half of a PATCH: what the page says, and who last said it.
+   *
+   * `updated_at` and `updated_by` are stamped here and nowhere else, so a request
+   * that only moved the page leaves them alone. Re-reads instead of writing when
+   * nothing about the content changed, because the row may still have been
+   * renumbered by the move that ran first.
+   */
+  async function writeContent(
+    tx: Transaction,
+    workspaceId: string,
+    id: string,
+    columns: Partial<repository.HandbookPageColumns>,
+    actor: Actor,
+    changed: boolean,
+  ): Promise<HandbookPageRecord | undefined> {
+    if (!changed) {
+      return repository.findPage(tx, workspaceId, id)
+    }
+
+    try {
+      return await repository.updatePage(tx, workspaceId, id, {
+        ...columns,
+        updatedBy: actorMemberId(actor),
+        updatedAt: dependencies.now(),
+      })
+    } catch (error: unknown) {
+      if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+        throw duplicateSlug()
+      }
+
+      throw error
+    }
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, HANDBOOK_PAGE_SORTS, DEFAULT_HANDBOOK_PAGE_SORT)
+      const rows = await repository.listPages(dependencies.db, workspaceId, filters, window)
+
+      return mapPage(toPage(rows, window, (page) => page.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('handbookPage')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const all = await repository.listAllPages(tx, workspaceId)
+
+        if (input.parentId !== null) {
+          const parent = all.find((page) => page.id === input.parentId)
+
+          if (parent === undefined) {
+            throw moveRefused('missing_parent')
+          }
+
+          // A new page carries no subtree, so its own depth is the whole check.
+          if (depthOf(all, parent.id) + 1 > MAX_DEPTH) {
+            throw moveRefused('too_deep')
+          }
+        }
+
+        const taken = new Set(all.map((page) => page.slug))
+        const siblings = childrenOf(all, input.parentId)
+
+        try {
+          const created = await repository.insertPage(tx, {
+            id,
+            workspaceId,
+            title: input.title,
+            slug: input.slug ?? uniqueSlug(taken, slugFromTitle(input.title)),
+            parentId: input.parentId,
+            sortOrder: siblings.length,
+            body: input.body,
+            updatedBy: actorMemberId(actor),
+          })
+
+          events.emit('record.created', {
+            workspaceId,
+            objectType: 'handbook_page',
+            recordId: id,
+          })
+
+          return toView(created)
+        } catch (error: unknown) {
+          // A slug given by the caller, or two concurrent creates that derived
+          // the same one from the same read of `taken`.
+          if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+            throw duplicateSlug()
+          }
+
+          throw error
+        }
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+      const columns = {
+        ...(changes.title === undefined ? {} : { title: changes.title }),
+        ...(changes.body === undefined ? {} : { body: changes.body }),
+        ...(changes.slug === undefined ? {} : { slug: changes.slug }),
+      }
+      const written = changedKeys(existing, columns)
+      const moves = changes.parentId !== undefined || changes.sortOrder !== undefined
+
+      if (written.length === 0 && !moves) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const movedFields = moves
+          ? await move(
+              tx,
+              workspaceId,
+              existing,
+              changes.parentId === undefined ? existing.parentId : changes.parentId,
+              changes.sortOrder,
+            )
+          : []
+
+        const updated = await writeContent(tx, workspaceId, id, columns, actor, written.length > 0)
+
+        if (updated === undefined) {
+          throw AppError.notFound('Handbook page not found')
+        }
+
+        const changed = [...written, ...movedFields]
+
+        if (changed.length > 0) {
+          events.emit('record.updated', {
+            workspaceId,
+            objectType: 'handbook_page',
+            recordId: id,
+            changedFields: changed,
+          })
+        }
+
+        return toView(updated)
+      })
+    },
+
+    /**
+     * Deletes the page and every page nested under it.
+     *
+     * The subtree goes through the self-referencing foreign key's cascade, so the
+     * ids are read first: a webhook consumer mirroring the handbook needs one
+     * `record.deleted` per page that is gone, not one for the page a person
+     * happened to click on.
+     *
+     * Siblings shifting up afterwards emit nothing. A consumer that mirrors order
+     * re-reads the sibling set, which is the same thing it does after a drag.
+     */
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx, events }) => {
+        const all = await repository.listAllPages(tx, workspaceId)
+        const page = all.find((candidate) => candidate.id === id)
+
+        if (page === undefined) {
+          throw AppError.notFound('Handbook page not found')
+        }
+
+        const removed = [id, ...descendantIds(all, id)]
+
+        await repository.deletePage(tx, workspaceId, id)
+        await renumber(
+          tx,
+          workspaceId,
+          childrenOf(all, page.parentId).filter((sibling) => sibling.id !== id),
+          undefined,
+        )
+
+        for (const recordId of removed) {
+          events.emit('record.deleted', { workspaceId, objectType: 'handbook_page', recordId })
+        }
+      })
+    },
+  }
+}

package/src/modules/handbook/slugs.ts

@@ -0,0 +1,54 @@
+/**
+ * Handbook slugs: the stable handle a page is addressed by.
+ *
+ * Hyphenated rather than the underscores a pipeline stage uses, because these are
+ * the ones already written down. `onboarding.md` seeds `ideal-customer-profile`,
+ * and `agent-tasks.md` names pages by exactly those strings in a task's
+ * `handbookSlugs`.
+ */
+
+/** Long enough for a real page title, short enough to stay a handle. Matches the route's `slug` bound. */
+export const MAX_SLUG_LENGTH = 100
+
+/** What the API accepts as a hand-written slug: lowercase words joined by single hyphens. */
+export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u
+
+/**
+ * A slug derived from a page title: accents stripped, lowercased, runs of
+ * anything else collapsed to one hyphen.
+ *
+ * @returns `page` for a title that leaves nothing behind, the way `Term sheet`
+ *   leaves `term_sheet` but `!!!` leaves nothing at all.
+ */
+export function slugFromTitle(title: string): string {
+  const slug = title
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, MAX_SLUG_LENGTH)
+    .replace(/-+$/gu, '')
+
+  return slug.length === 0 ? 'page' : slug
+}
+
+/**
+ * `pricing`, `pricing-2`, `pricing-3`: two pages may share a title, and the
+ * unique index means they may not share a slug.
+ *
+ * @param taken Every slug already in the workspace.
+ */
+export function uniqueSlug(taken: ReadonlySet<string>, base: string): string {
+  if (!taken.has(base)) {
+    return base
+  }
+
+  for (let suffix = 2; ; suffix += 1) {
+    const candidate = `${base.slice(0, MAX_SLUG_LENGTH - 1 - String(suffix).length)}-${String(suffix)}`
+
+    if (!taken.has(candidate)) {
+      return candidate
+    }
+  }
+}

package/src/modules/handbook/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 { createBody, handbookPageResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { HandbookService } from './service.ts'
+
+/** `handbook_pages_*`. Same schemas and mappers as `/v1/handbook_pages`. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg.describe('Free text over the title and the body. This is how you search the handbook.'),
+  slug: idSetArg.optional().describe('Fetch pages by their stable slug rather than by id.'),
+})
+
+export function registerHandbookTools(mcp: McpToolRegistry, service: HandbookService): void {
+  registerCrudTools(mcp, {
+    resource: 'handbook_pages',
+    subject: 'handbook page',
+    about:
+      'A markdown page of company knowledge: voice, ICP, how we sell, case studies. ' +
+      'Read these before writing anything a customer will see.',
+    service,
+    render: handbookPageResponse,
+    listArgs,
+    toFilters: (args) => ({ term: args.q, slugs: toSet(args.slug) }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/handbook/tree.ts

@@ -0,0 +1,158 @@
+/**
+ * The handbook tree's rules, as plain functions over the rows.
+ *
+ * A self-referencing foreign key can express a tree but not its bounds: nothing
+ * in Postgres refuses a page nested under its own child, and nothing counts
+ * levels. `schema.md` puts both in the service, and they live here rather than in
+ * `service.ts` so they can be exercised without a database.
+ *
+ * Every function takes one workspace's pages. They are small enough to walk in
+ * memory, and a single snapshot is what makes a sequence of checks agree with
+ * each other.
+ */
+
+/**
+ * How deep a page may sit, counting a top-level page as 0.
+ *
+ * Four, the mockup's `MAX_DEPTH`, so five levels are reachable. The cap exists
+ * because the sidebar indents by a fixed 14px per level and a sixth level has
+ * nowhere left to go in a 260px column.
+ */
+export const MAX_DEPTH = 4
+
+/** What the tree rules need off a page. The service passes stored rows, which carry more. */
+export interface TreeNode {
+  readonly id: string
+  readonly parentId: string | null
+  readonly sortOrder: number
+}
+
+/**
+ * One parent's children, in sibling order. `parentId: null` gives the top level.
+ *
+ * The id tiebreak never fires while the service keeps a sibling set contiguous
+ * from 0, but two rows sharing a position must still come back in a fixed order
+ * rather than the one the planner happened to choose.
+ */
+export function childrenOf<TNode extends TreeNode>(
+  nodes: readonly TNode[],
+  parentId: string | null,
+): TNode[] {
+  return nodes
+    .filter((node) => node.parentId === parentId)
+    .sort((left, right) => left.sortOrder - right.sortOrder || left.id.localeCompare(right.id))
+}
+
+/** Every page under this one, at any depth. The set a delete takes with it, and the set a move may not land in. */
+export function descendantIds(nodes: readonly TreeNode[], rootId: string): ReadonlySet<string> {
+  const found = new Set<string>()
+  const pending = [rootId]
+
+  while (pending.length > 0) {
+    const parentId = pending.pop()
+
+    for (const child of nodes.filter((node) => node.parentId === parentId)) {
+      // A cycle would loop forever. The service cannot create one, but this
+      // walks whatever is in the table rather than trusting that.
+      if (!found.has(child.id)) {
+        found.add(child.id)
+        pending.push(child.id)
+      }
+    }
+  }
+
+  return found
+}
+
+/**
+ * How deep a page sits, counting a top-level page as 0.
+ *
+ * @returns The depth, or `MAX_DEPTH + 1` if the chain above the page is broken
+ *   or circular. That is deliberately over the cap: a page whose ancestry cannot
+ *   be resolved must fail a depth check rather than pass one.
+ */
+export function depthOf(nodes: readonly TreeNode[], id: string): number {
+  const byId = new Map(nodes.map((node) => [node.id, node]))
+  let cursor = byId.get(id)?.parentId ?? null
+  let depth = 0
+
+  while (cursor !== null) {
+    depth += 1
+
+    if (depth > MAX_DEPTH) {
+      return MAX_DEPTH + 1
+    }
+
+    cursor = byId.get(cursor)?.parentId ?? null
+  }
+
+  return depth
+}
+
+/** How many levels sit below a page: 0 when it has no children. A move carries this with it. */
+export function subtreeHeight(nodes: readonly TreeNode[], rootId: string): number {
+  const children = nodes.filter((node) => node.parentId === rootId)
+
+  if (children.length === 0) {
+    return 0
+  }
+
+  return 1 + Math.max(...children.map((child) => subtreeHeight(nodes, child.id)))
+}
+
+/** Why a move was refused. The service turns each into a 422 with its own message. */
+export type MoveRejection = 'self' | 'descendant' | 'missing_parent' | 'too_deep'
+
+/**
+ * Whether a page may become a child of `parentId`.
+ *
+ * The three refusals are different mistakes and the caller is told which. Depth
+ * counts the whole subtree, not just the page: re-nesting a branch three levels
+ * tall under a level-two parent would push its leaves past the cap even though
+ * the page itself lands inside it.
+ *
+ * @param parentId The proposed parent, or null for the top level.
+ * @returns undefined when the move is allowed.
+ */
+export function rejectMove(
+  nodes: readonly TreeNode[],
+  pageId: string,
+  parentId: string | null,
+): MoveRejection | undefined {
+  if (parentId === null) {
+    return subtreeHeight(nodes, pageId) > MAX_DEPTH ? 'too_deep' : undefined
+  }
+
+  if (parentId === pageId) {
+    return 'self'
+  }
+
+  if (!nodes.some((node) => node.id === parentId)) {
+    return 'missing_parent'
+  }
+
+  if (descendantIds(nodes, pageId).has(parentId)) {
+    return 'descendant'
+  }
+
+  return depthOf(nodes, parentId) + 1 + subtreeHeight(nodes, pageId) > MAX_DEPTH
+    ? 'too_deep'
+    : undefined
+}
+
+/**
+ * A sibling set with one page placed at `position`, 0-based.
+ *
+ * @param siblings The set the page is joining, in order, without the page itself.
+ * @param position Where it lands. Past the end is the end, which is what an
+ *   absent position means and what a drag to the bottom of a list produces.
+ */
+export function placeAt<TNode extends TreeNode>(
+  siblings: readonly TNode[],
+  page: TNode,
+  position: number,
+): TNode[] {
+  const index = Math.max(0, Math.min(position, siblings.length))
+
+  return [...siblings.slice(0, index), page, ...siblings.slice(index)]
+}