@kelpie/server 0.1.0

package/src/modules/handbook/repository.ts

@@ -0,0 +1,173 @@
+import { and, asc, eq, ilike, inArray, isNull, or } 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 { handbookPages } from './schema.ts'
+
+export type HandbookPageRecord = typeof handbookPages.$inferSelect
+
+/** The writable column shape. The service builds these; nothing else knows the column names. */
+export type HandbookPageColumns = typeof handbookPages.$inferInsert
+
+/**
+ * `sort_order` is not here, and cannot be: it orders a page among its siblings
+ * only, so two pages under different parents share positions and a workspace-wide
+ * sort by it would interleave the levels into nonsense. The tree is rebuilt by
+ * the caller from `parent_id` and `sort_order`, which is what the mockup's
+ * `flattenTree` does.
+ */
+export const HANDBOOK_PAGE_SORTS: SortableFields<HandbookPageRecord> = {
+  title: textSort(handbookPages.title, (page) => page.title),
+  created_at: timestampSort(handbookPages.createdAt, (page) => page.createdAt),
+  updated_at: timestampSort(handbookPages.updatedAt, (page) => page.updatedAt),
+}
+
+/**
+ * Alphabetical, not `-created_at` like the CRM resources.
+ *
+ * A handbook is read, not triaged. Newest-first would open on Agent FAQ and bury
+ * About us, and the creation order of the starter pages is an implementation
+ * detail of the seed rather than anything a reader asked for.
+ */
+export const DEFAULT_HANDBOOK_PAGE_SORT = 'title'
+
+export interface HandbookPageFilters {
+  /** `?q=`: title and body. A handbook is searched for what it says, not only for what it is called. */
+  readonly term?: string | undefined
+  /** `?slug=`, repeatable: the stable handle agent tasks name pages by (`agent-tasks.md`). */
+  readonly slugs?: readonly string[] | undefined
+}
+
+function conditionsFor(workspaceId: string, filters: HandbookPageFilters): (SQL | undefined)[] {
+  const pattern = filters.term === undefined ? undefined : containsPattern(filters.term)
+
+  return [
+    eq(handbookPages.workspaceId, workspaceId),
+    pattern === undefined
+      ? undefined
+      : or(ilike(handbookPages.title, pattern), ilike(handbookPages.body, pattern)),
+    filters.slugs === undefined ? undefined : inArray(handbookPages.slug, filters.slugs),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listPages(
+  db: Queryable,
+  workspaceId: string,
+  filters: HandbookPageFilters,
+  window: ListWindow<HandbookPageRecord>,
+): Promise<HandbookPageRecord[]> {
+  return db
+    .select()
+    .from(handbookPages)
+    .where(
+      and(...conditionsFor(workspaceId, filters), keysetCondition(window, handbookPages.id)),
+    )
+    .orderBy(...orderByWindow(window, handbookPages.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findPage(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<HandbookPageRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(handbookPages)
+    .where(and(eq(handbookPages.workspaceId, workspaceId), eq(handbookPages.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * Every page in the workspace, in sibling order.
+ *
+ * The tree rules (depth, no-descendant-cycles, sibling renumbering) all need the
+ * whole tree, and a workspace handbook is small enough to walk in memory. Reading
+ * it once beats one query per level, and inside a transaction it is the snapshot
+ * every check in that transaction agrees on.
+ */
+export function listAllPages(
+  db: Queryable,
+  workspaceId: string,
+): Promise<HandbookPageRecord[]> {
+  return db
+    .select()
+    .from(handbookPages)
+    .where(eq(handbookPages.workspaceId, workspaceId))
+    .orderBy(asc(handbookPages.sortOrder), asc(handbookPages.id))
+}
+
+/** One parent's children, in board order. Used to renumber a sibling set after a move or a delete. */
+export function listChildren(
+  db: Queryable,
+  workspaceId: string,
+  parentId: string | null,
+): Promise<HandbookPageRecord[]> {
+  return db
+    .select()
+    .from(handbookPages)
+    .where(
+      and(
+        eq(handbookPages.workspaceId, workspaceId),
+        parentId === null ? isNull(handbookPages.parentId) : eq(handbookPages.parentId, parentId),
+      ),
+    )
+    .orderBy(asc(handbookPages.sortOrder), asc(handbookPages.id))
+}
+
+/** The slugs already taken in this workspace, for deriving a unique one from a title. */
+export async function listSlugs(db: Queryable, workspaceId: string): Promise<ReadonlySet<string>> {
+  const rows = await db
+    .select({ slug: handbookPages.slug })
+    .from(handbookPages)
+    .where(eq(handbookPages.workspaceId, workspaceId))
+
+  return new Set(rows.map((row) => row.slug))
+}
+
+export async function insertPage(
+  db: Queryable,
+  values: HandbookPageColumns,
+): Promise<HandbookPageRecord> {
+  const [created] = await db.insert(handbookPages).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting handbook page ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updatePage(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<HandbookPageColumns>,
+): Promise<HandbookPageRecord | undefined> {
+  const [updated] = await db
+    .update(handbookPages)
+    .set(changes)
+    .where(and(eq(handbookPages.workspaceId, workspaceId), eq(handbookPages.id, id)))
+    .returning()
+
+  return updated
+}
+
+/**
+ * Deletes one page. The self-referencing foreign key is `on delete cascade`, so
+ * the subtree goes with it without this function naming a single descendant.
+ */
+export async function deletePage(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(handbookPages)
+    .where(and(eq(handbookPages.workspaceId, workspaceId), eq(handbookPages.id, id)))
+    .returning({ id: handbookPages.id })
+
+  return deleted.length
+}

package/src/modules/handbook/routes.ts

@@ -0,0 +1,145 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+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 { MAX_SLUG_LENGTH, SLUG_PATTERN } from './slugs.ts'
+import type {
+  CreateHandbookPageInput,
+  HandbookPageView,
+  HandbookService,
+  UpdateHandbookPageInput,
+} from './service.ts'
+
+/**
+ * Wire shapes for `/v1/handbook_pages`. Bodies are strict; an unknown field is a
+ * 422, per `api.md`.
+ */
+
+const slugField = z
+  .string()
+  .min(1)
+  .max(MAX_SLUG_LENGTH)
+  .regex(SLUG_PATTERN, 'Use lowercase words joined by hyphens')
+
+/**
+ * `slug` is optional on both verbs and stays put on a rename.
+ *
+ * The mockup rewrites a page's slug every time its title is edited. Agent tasks
+ * name handbook pages by slug (`agent-tasks.md`), so a slug that follows the
+ * title would break a task definition the first time somebody fixes a typo. This
+ * is the rule pipeline stages already follow: the label renames, the import alias
+ * does not. Moving a slug on purpose is a separate field in the same request.
+ */
+export const createBody = z.strictObject({
+  title: z.string().min(1),
+  body: z.string().default(''),
+  slug: slugField.optional(),
+  parent_id: z.string().min(1).nullable().default(null),
+})
+
+/**
+ * `parent_id` and `sort_order` are the move. `null` on `parent_id` lifts a page
+ * to the top level, which is what `api.md` says null means on a nullable field.
+ */
+export const updateBody = z
+  .strictObject({
+    title: z.string().min(1),
+    body: z.string(),
+    slug: slugField,
+    parent_id: z.string().min(1).nullable(),
+    sort_order: z.number().int().min(0),
+  })
+  .partial()
+
+export interface HandbookRoutesDependencies extends CredentialDependencies {
+  readonly service: HandbookService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateHandbookPageInput {
+  return {
+    title: body.title,
+    body: body.body,
+    slug: body.slug,
+    parentId: body.parent_id,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateHandbookPageInput {
+  return {
+    ...(body.title === undefined ? {} : { title: body.title }),
+    ...(body.body === undefined ? {} : { body: body.body }),
+    ...(body.slug === undefined ? {} : { slug: body.slug }),
+    ...(body.parent_id === undefined ? {} : { parentId: body.parent_id }),
+    ...(body.sort_order === undefined ? {} : { sortOrder: body.sort_order }),
+  }
+}
+
+export function handbookPageResponse(page: HandbookPageView): Record<string, unknown> {
+  return {
+    id: page.id,
+    title: page.title,
+    slug: page.slug,
+    parent_id: page.parentId,
+    sort_order: page.sortOrder,
+    body: page.body,
+    updated_by: page.updatedBy,
+    created_at: page.createdAt.toISOString(),
+    updated_at: page.updatedAt.toISOString(),
+  }
+}
+
+export function mountHandbookRoutes(router: Hono, dependencies: HandbookRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/handbook_pages', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        // `readIdFilter` despite these being slugs: the shape is the one it
+        // enforces — repeatable, blank refused, capped at a page of them — and a
+        // task resolving its `handbookSlugs` asks about a set exactly that way.
+        slugs: readIdFilter(context, 'slug'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, handbookPageResponse))
+  })
+
+  router.post('/handbook_pages', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const page = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(handbookPageResponse(page), 201)
+  })
+
+  router.get('/handbook_pages/:id', async (context) => {
+    const page = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(handbookPageResponse(page))
+  })
+
+  router.patch('/handbook_pages/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const page = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(handbookPageResponse(page))
+  })
+
+  router.delete('/handbook_pages/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/handbook/schema.ts

@@ -0,0 +1,43 @@
+import { type AnyPgColumn, index, integer, pgTable, text, unique } from 'drizzle-orm/pg-core'
+
+import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
+import type { SearchVectorPart } from '../../lib/columns.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+/**
+ * The company brain: nested markdown pages agents read over the same API as CRM
+ * records.
+ *
+ * Depth (max 4) and the no-descendant-cycles rule are enforced in the service
+ * layer; a self-referencing foreign key can express the tree but not its bounds.
+ */
+export const handbookPages = pgTable(
+  'handbook_pages',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    title: text('title').notNull(),
+    slug: text('slug').notNull(),
+    parentId: text('parent_id').references((): AnyPgColumn => handbookPages.id, { onDelete: 'cascade' }),
+    sortOrder: integer('sort_order').notNull(),
+    body: text('body').notNull().default(''),
+    updatedBy: text('updated_by').references(() => workspaceMembers.id, { onDelete: 'set null' }),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    // The body is markdown, and it is indexed as-is. Postgres tokenises `##` and
+    // `**` as punctuation, so the syntax costs nothing and stripping it first
+    // would mean a second copy of every page to keep in step.
+    searchVector: searchVector((): readonly SearchVectorPart[] => [
+      { column: handbookPages.title, weight: 'A' },
+      { column: handbookPages.slug, weight: 'B' },
+      { column: handbookPages.body, weight: 'B' },
+    ]),
+  },
+  (table) => [
+    unique('handbook_pages_workspace_slug_key').on(table.workspaceId, table.slug),
+    index('handbook_pages_parent_idx').on(table.workspaceId, table.parentId),
+    index('handbook_pages_search_idx').using('gin', table.searchVector),
+  ],
+)