@kelpie/server 0.1.0

package/dist/modules/handbook/service.js

@@ -0,0 +1,246 @@
+import { changedKeys } from '../../lib/changes.js';
+import { UNIQUE_VIOLATION, postgresErrorCode } from '../../lib/database.js';
+import { AppError } from '../../lib/errors.js';
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.js';
+import { actorMemberId, requireWorkspaceId } from '../auth/actor.js';
+import * as repository from './repository.js';
+import { DEFAULT_HANDBOOK_PAGE_SORT, HANDBOOK_PAGE_SORTS } from './repository.js';
+import { slugFromTitle, uniqueSlug } from './slugs.js';
+import { MAX_DEPTH, childrenOf, depthOf, descendantIds, placeAt, rejectMove } from './tree.js';
+function toView(record) {
+    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) {
+    const messages = {
+        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() {
+    return AppError.conflict('A handbook page in this workspace already uses that address', [
+        { field: 'slug', message: 'Already in use' },
+    ]);
+}
+export function createHandbookService(dependencies) {
+    async function require(workspaceId, id) {
+        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, workspaceId, order, reparented) {
+        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, workspaceId, page, parentId, position) {
+        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, page) {
+        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, workspaceId, id, columns, actor, changed) {
+        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) {
+            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) {
+                    // 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 });
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/modules/handbook/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/modules/handbook/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/handbook/slugs.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const MAX_SLUG_LENGTH = 100;
+/** What the API accepts as a hand-written slug: lowercase words joined by single hyphens. */
+export declare const SLUG_PATTERN: RegExp;
+/**
+ * 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 declare function slugFromTitle(title: string): string;
+/**
+ * `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 declare function uniqueSlug(taken: ReadonlySet<string>, base: string): string;
+//# sourceMappingURL=slugs.d.ts.map

package/dist/modules/handbook/slugs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugs.d.ts","sourceRoot":"","sources":["../../../src/modules/handbook/slugs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0GAA0G;AAC1G,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC,6FAA6F;AAC7F,eAAO,MAAM,YAAY,QAAgC,CAAA;AAEzD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWnD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAY3E"}

package/dist/modules/handbook/slugs.js

@@ -0,0 +1,48 @@
+/**
+ * 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) {
+    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, base) {
+    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;
+        }
+    }
+}
+//# sourceMappingURL=slugs.js.map

package/dist/modules/handbook/slugs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugs.js","sourceRoot":"","sources":["../../../src/modules/handbook/slugs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0GAA0G;AAC1G,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAA;AAElC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,6BAA6B,CAAA;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,IAAI,GAAG,KAAK;SACf,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,WAAW,EAAE;SACb,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;SACzB,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAEvB,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAA0B,EAAE,IAAY;IACjE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,IAAI,MAAM,GAAG,CAAC,GAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAA;QAEnG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/modules/handbook/tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpToolRegistry } from '../../runtime/module.ts';
+import type { HandbookService } from './service.ts';
+export declare function registerHandbookTools(mcp: McpToolRegistry, service: HandbookService): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/modules/handbook/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/modules/handbook/tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAG9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAUnD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAgB1F"}

package/dist/modules/handbook/tools.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.js';
+import { createBody, handbookPageResponse, toCreateInput, toUpdateInput, updateBody } from './routes.js';
+/** `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, service) {
+    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,
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/modules/handbook/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/modules/handbook/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACrG,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxG,4EAA4E;AAE5E,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC;IAC9B,GAAG,eAAe;IAClB,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,6EAA6E,CAAC;IAClG,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;CAC1F,CAAC,CAAA;AAEF,MAAM,UAAU,qBAAqB,CAAC,GAAoB,EAAE,OAAwB;IAClF,iBAAiB,CAAC,GAAG,EAAE;QACrB,QAAQ,EAAE,gBAAgB;QAC1B,OAAO,EAAE,eAAe;QACxB,KAAK,EACH,+EAA+E;YAC/E,yDAAyD;QAC3D,OAAO;QACP,MAAM,EAAE,oBAAoB;QAC5B,QAAQ;QACR,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChE,UAAU,EAAE,UAAU;QACtB,aAAa;QACb,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QAC5C,aAAa;KACd,CAAC,CAAA;AACJ,CAAC"}

package/dist/modules/handbook/tree.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 declare 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 declare function childrenOf<TNode extends TreeNode>(nodes: readonly TNode[], parentId: string | null): TNode[];
+/** 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 declare function descendantIds(nodes: readonly TreeNode[], rootId: string): ReadonlySet<string>;
+/**
+ * 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 declare function depthOf(nodes: readonly TreeNode[], id: string): number;
+/** How many levels sit below a page: 0 when it has no children. A move carries this with it. */
+export declare function subtreeHeight(nodes: readonly TreeNode[], rootId: string): number;
+/** 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 declare function rejectMove(nodes: readonly TreeNode[], pageId: string, parentId: string | null): MoveRejection | 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 declare function placeAt<TNode extends TreeNode>(siblings: readonly TNode[], page: TNode, position: number): TNode[];
+//# sourceMappingURL=tree.d.ts.map

package/dist/modules/handbook/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/modules/handbook/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,IAAI,CAAA;AAE1B,6FAA6F;AAC7F,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,SAAS,QAAQ,EAC/C,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,KAAK,EAAE,CAIT;AAED,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAkB7F;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAgBtE;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQhF;AAED,sFAAsF;AACtF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,gBAAgB,GAAG,UAAU,CAAA;AAEjF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,aAAa,GAAG,SAAS,CAoB3B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,SAAS,QAAQ,EAC5C,QAAQ,EAAE,SAAS,KAAK,EAAE,EAC1B,IAAI,EAAE,KAAK,EACX,QAAQ,EAAE,MAAM,GACf,KAAK,EAAE,CAIT"}

package/dist/modules/handbook/tree.js

@@ -0,0 +1,117 @@
+/**
+ * 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;
+/**
+ * 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(nodes, parentId) {
+    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, rootId) {
+    const found = new Set();
+    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, id) {
+    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, rootId) {
+    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)));
+}
+/**
+ * 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, pageId, parentId) {
+    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(siblings, page, position) {
+    const index = Math.max(0, Math.min(position, siblings.length));
+    return [...siblings.slice(0, index), page, ...siblings.slice(index)];
+}
+//# sourceMappingURL=tree.js.map

package/dist/modules/handbook/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/modules/handbook/tree.ts"],"names":[],"mappings":"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"}