@anchrd/intel-api 0.12.0 → 0.12.2

package/dist/nodes/board/board.d.ts

@@ -0,0 +1,15 @@
+import type { BoardDeps, BoardOperations } from "./board.types.js";
+/**
+ * Every board operation, applied to the document rather than to the file (#285).
+ *
+ * ⚠️ This module is where a board's rules live, and it is deliberately pure: it takes a document
+ * and gives back the next one. The version, R2 and the retry against a racing write are the
+ * service's business (`nodes.ts`), and the surfaces have no rules of their own — HTTP, MCP and the
+ * UI all arrive here. A second implementation of "may this task depend on that one" is the thing
+ * this shape exists to prevent.
+ *
+ * ⚠️ What it does NOT check is anything that needs the tree: whether a `references` id names a node
+ * the writer may see, and whether an `agent` assignee is really an agent. Those are reads against
+ * D1 and the ACL, so they happen in the service before the document is touched at all.
+ */
+export declare function createBoard(deps: BoardDeps): BoardOperations;

package/dist/nodes/board/board.js

@@ -0,0 +1,359 @@
+import { ArchivedBoardStatusId, BoardDefaultStatuses, BoardMaxTaskDepth, } from "@anchrd/intel-contract";
+import { generateKeyBetween } from "fractional-indexing";
+import { IntelError } from "../../shared/intel-error/intel-error.js";
+/**
+ * Every board operation, applied to the document rather than to the file (#285).
+ *
+ * ⚠️ This module is where a board's rules live, and it is deliberately pure: it takes a document
+ * and gives back the next one. The version, R2 and the retry against a racing write are the
+ * service's business (`nodes.ts`), and the surfaces have no rules of their own — HTTP, MCP and the
+ * UI all arrive here. A second implementation of "may this task depend on that one" is the thing
+ * this shape exists to prevent.
+ *
+ * ⚠️ What it does NOT check is anything that needs the tree: whether a `references` id names a node
+ * the writer may see, and whether an `agent` assignee is really an agent. Those are reads against
+ * D1 and the ACL, so they happen in the service before the document is touched at all.
+ */
+export function createBoard(deps) {
+    function byOrder(left, right) {
+        // The id breaks a tie that cannot happen: two keys are distinct by construction. It is here so
+        // the sort is total, because an unstable order would make two readers of the same board
+        // disagree about which card comes first.
+        if (left.order === right.order)
+            return left.id < right.id ? -1 : 1;
+        return left.order < right.order ? -1 : 1;
+    }
+    function sorted(tasks) {
+        return [...tasks].sort(byOrder);
+    }
+    function taskOf(board, taskId) {
+        const task = board.tasks.find((candidate) => candidate.id === taskId);
+        if (!task)
+            throw new IntelError(404, "board_task_not_found", "Task was not found");
+        return task;
+    }
+    function requireStatus(board, statusId) {
+        if (!board.statuses.some((status) => status.id === statusId)) {
+            throw new IntelError(422, "board_status_unknown", `This board has no status “${statusId}”`);
+        }
+    }
+    // The column a task lands in when nobody says otherwise: the first one that is not the shelf.
+    function firstOpenStatus(board) {
+        const open = [...board.statuses]
+            .sort((left, right) => left.order - right.order)
+            .find((status) => status.id !== ArchivedBoardStatusId);
+        if (!open) {
+            throw new IntelError(409, "board_status_unknown", "This board has no status a task could be added to");
+        }
+        return open.id;
+    }
+    function childrenOf(tasks) {
+        const children = new Map();
+        for (const task of tasks) {
+            const siblings = children.get(task.parentId);
+            if (siblings)
+                siblings.push(task);
+            else
+                children.set(task.parentId, [task]);
+        }
+        return children;
+    }
+    /**
+     * The task and everything under it, breadth first.
+     *
+     * ⚠️ The walk is bounded by the number of tasks rather than by the depth, so a board whose
+     * `parentId` chain somehow closed on itself — one written before the cycle check, or restored
+     * from a bundle — is counted once and does not spin here.
+     */
+    function withDescendants(tasks, rootId) {
+        const children = childrenOf(tasks);
+        const removed = new Set([rootId]);
+        const queue = [rootId];
+        for (let index = 0; index < queue.length; index += 1) {
+            const current = queue[index];
+            if (current === undefined)
+                continue;
+            for (const child of children.get(current) ?? []) {
+                if (removed.has(child.id))
+                    continue;
+                removed.add(child.id);
+                queue.push(child.id);
+            }
+        }
+        return removed;
+    }
+    function depthOf(tasks, taskId) {
+        let depth = 0;
+        let current = taskId;
+        const seen = new Set();
+        while (current !== null) {
+            if (seen.has(current))
+                break;
+            seen.add(current);
+            depth += 1;
+            current = tasks.find((task) => task.id === current)?.parentId ?? null;
+        }
+        return depth;
+    }
+    function heightOf(tasks, rootId) {
+        const children = childrenOf(tasks);
+        let height = 1;
+        let level = [rootId];
+        const seen = new Set(level);
+        while (level.length > 0) {
+            const next = [];
+            for (const id of level) {
+                for (const child of children.get(id) ?? []) {
+                    if (seen.has(child.id))
+                        continue;
+                    seen.add(child.id);
+                    next.push(child.id);
+                }
+            }
+            if (next.length > 0)
+                height += 1;
+            level = next;
+        }
+        return height;
+    }
+    /**
+     * Whether this task may hang under that parent (#285).
+     *
+     * ⚠️ Two refusals, not one, because they are two different mistakes. Hanging a task under its own
+     * descendant is a cycle — a subtree that has left the board without being deleted, invisible in
+     * every view. Hanging a legal subtree too deep is a bound: `BoardMaxTaskDepth` counts the whole
+     * chain, so moving an epic under another epic is measured with its own children, not as if it
+     * were a single card.
+     */
+    function requireParent(tasks, taskId, parentId) {
+        if (parentId === null)
+            return;
+        if (parentId === taskId) {
+            throw new IntelError(409, "board_parent_cycle", "A task cannot be its own parent");
+        }
+        if (!tasks.some((task) => task.id === parentId)) {
+            throw new IntelError(422, "board_parent_unknown", "The parent task is not on this board");
+        }
+        if (withDescendants(tasks, taskId).has(parentId)) {
+            throw new IntelError(409, "board_parent_cycle", "A task cannot be moved under one of its own subtasks");
+        }
+        const depth = depthOf(tasks, parentId) + heightOf(tasks, taskId);
+        if (depth > BoardMaxTaskDepth) {
+            throw new IntelError(422, "board_depth_exceeded", `Tasks nest at most ${BoardMaxTaskDepth} deep, and this would be ${depth}`);
+        }
+    }
+    /**
+     * Whether these dependencies exist here and describe no circle (#285).
+     *
+     * ⚠️ A dependency on a task this board does not hold is refused BECAUSE it might be a task in
+     * another board. Accepting it would hang this node on a file that can be edited, moved or deleted
+     * without anything here noticing — across boards the link is `references`, which names the board
+     * NODE and is a link the graph can see. "Unknown" and "in another board" are deliberately the same
+     * refusal: telling them apart would mean confirming that a task id exists somewhere the caller may
+     * have no access to.
+     *
+     * ⚠️ Own check, run over the whole graph and separate from the `parentId` walk. The two describe
+     * different things — where a card sits and what it waits for — and a subtask that waits for its
+     * own epic is legal in one and would be a cycle in the other.
+     */
+    function requireDependencies(tasks, taskId) {
+        const byId = new Map(tasks.map((task) => [task.id, task]));
+        for (const task of tasks) {
+            for (const dependency of task.dependsOn) {
+                if (!byId.has(dependency)) {
+                    throw new IntelError(422, "board_dependency_unknown", `A task can only depend on a task of the same board, and “${dependency}” is not one`);
+                }
+            }
+        }
+        // Depth-first from the changed task alone: everything else was acyclic before this write, so a
+        // circle that exists now has to run through the one task that changed.
+        const stack = [taskId];
+        const path = new Set();
+        const done = new Set();
+        const visit = (id) => {
+            if (done.has(id))
+                return;
+            if (path.has(id)) {
+                throw new IntelError(409, "board_dependency_cycle", "These dependencies would wait for each other in a circle");
+            }
+            path.add(id);
+            for (const dependency of byId.get(id)?.dependsOn ?? [])
+                visit(dependency);
+            path.delete(id);
+            done.add(id);
+        };
+        for (const id of stack)
+            visit(id);
+    }
+    /**
+     * The order key for a task's new place.
+     *
+     * ⚠️ Neighbours are read from the board's ONE key space rather than from the target column. A key
+     * minted between two cards is between them globally, and a filtered view of a sorted list is still
+     * sorted, so a column shows exactly what the caller asked for while no second key space has to be
+     * kept in step with the first.
+     *
+     * With no neighbour named, the task goes last in the column it is landing in — which is what
+     * "add a task" means without further instruction, and what a drop onto an empty column means.
+     */
+    function placementKey(board, placement, movingTaskId) {
+        const others = sorted(board.tasks.filter((task) => task.id !== movingTaskId));
+        const indexOf = (taskId) => {
+            const index = others.findIndex((task) => task.id === taskId);
+            if (index < 0) {
+                throw new IntelError(422, "board_neighbour_unknown", "The neighbour task is not on this board");
+            }
+            return index;
+        };
+        let afterIndex = placement.afterTaskId === null ? null : indexOf(placement.afterTaskId);
+        const beforeIndex = placement.beforeTaskId === null ? null : indexOf(placement.beforeTaskId);
+        if (afterIndex !== null && beforeIndex !== null && afterIndex >= beforeIndex) {
+            throw new IntelError(400, "board_neighbour_order", "The task named as the predecessor does not come before the one named as the successor");
+        }
+        if (afterIndex === null && beforeIndex === null) {
+            const column = others.filter((task) => task.status === placement.status && task.parentId === placement.parentId);
+            const last = column.at(-1);
+            if (!last)
+                return generateKeyBetween(others.at(-1)?.order ?? null, null);
+            afterIndex = others.indexOf(last);
+        }
+        const lower = afterIndex === null ? null : (others[afterIndex]?.order ?? null);
+        const upper = beforeIndex !== null
+            ? (others[beforeIndex]?.order ?? null)
+            : afterIndex !== null
+                ? (others[afterIndex + 1]?.order ?? null)
+                : null;
+        return generateKeyBetween(lower, upper);
+    }
+    function replaced(board, task) {
+        return {
+            statuses: board.statuses,
+            tasks: board.tasks.map((candidate) => (candidate.id === task.id ? task : candidate)),
+        };
+    }
+    return {
+        defaultBoard() {
+            return { statuses: [...BoardDefaultStatuses], tasks: [] };
+        },
+        /**
+         * The status list, written whole.
+         *
+         * ⚠️ `archived` is asserted here as well as at the boundary, and that is not the usual
+         * duplication. It is the rule the whole "sweep it away instead of deleting it" promise rests
+         * on, and a board that lost its shelf cannot be repaired by the caller who lost it — every task
+         * sitting there would point at a status that no longer exists.
+         *
+         * ⚠️ A status that tasks still sit in cannot be dropped. The alternative — moving those tasks
+         * somewhere — is a decision about somebody's work, and this call is not the place to make it
+         * silently.
+         */
+        configure(board, statuses) {
+            if (!statuses.some((status) => status.id === ArchivedBoardStatusId)) {
+                throw new IntelError(422, "board_status_archived_required", `The “${ArchivedBoardStatusId}” status cannot be removed`);
+            }
+            const kept = new Set(statuses.map((status) => status.id));
+            const orphaned = board.tasks.find((task) => !kept.has(task.status));
+            if (orphaned) {
+                throw new IntelError(409, "board_status_in_use", `Tasks still sit in “${orphaned.status}”, so it cannot be removed`);
+            }
+            const next = statuses.map((status, index) => ({
+                id: status.id,
+                label: status.label,
+                order: index,
+            }));
+            return { statuses: next, tasks: board.tasks };
+        },
+        addTask(board, input) {
+            if (board.tasks.length >= 5_000) {
+                throw new IntelError(409, "board_task_limit", "This board holds as many tasks as it can");
+            }
+            const status = input.status ?? firstOpenStatus(board);
+            requireStatus(board, status);
+            const task = {
+                id: deps.id(),
+                title: input.title,
+                status,
+                assignee: input.assignee,
+                labels: input.labels,
+                startDate: input.startDate,
+                dueDate: input.dueDate,
+                parentId: input.parentId,
+                dependsOn: input.dependsOn,
+                order: placementKey(board, {
+                    status,
+                    parentId: input.parentId,
+                    afterTaskId: input.afterTaskId,
+                    beforeTaskId: input.beforeTaskId,
+                }, null),
+                description: input.description,
+                references: input.references,
+            };
+            const tasks = [...board.tasks, task];
+            requireParent(tasks, task.id, task.parentId);
+            requireDependencies(tasks, task.id);
+            return { board: { statuses: board.statuses, tasks }, task };
+        },
+        updateTask(board, input) {
+            const current = taskOf(board, input.taskId);
+            const task = {
+                ...current,
+                ...(input.title !== undefined && { title: input.title }),
+                ...(input.assignee !== undefined && { assignee: input.assignee }),
+                ...(input.labels !== undefined && { labels: input.labels }),
+                ...(input.startDate !== undefined && { startDate: input.startDate }),
+                ...(input.dueDate !== undefined && { dueDate: input.dueDate }),
+                ...(input.dependsOn !== undefined && { dependsOn: input.dependsOn }),
+                ...(input.description !== undefined && { description: input.description }),
+                ...(input.references !== undefined && { references: input.references }),
+            };
+            const next = replaced(board, task);
+            requireDependencies(next.tasks, task.id);
+            return { board: next, task };
+        },
+        moveTask(board, input) {
+            const current = taskOf(board, input.taskId);
+            const status = input.status ?? current.status;
+            requireStatus(board, status);
+            const parentId = input.parentId === undefined ? current.parentId : input.parentId;
+            // The parent is checked against the board as it stands, before the order key is minted: a
+            // refused move must not have spent one, and `placementKey` is the only step that cannot be
+            // undone by simply not returning the document.
+            requireParent(board.tasks, current.id, parentId);
+            const task = {
+                ...current,
+                status,
+                parentId,
+                order: placementKey(board, {
+                    status,
+                    parentId,
+                    afterTaskId: input.afterTaskId,
+                    beforeTaskId: input.beforeTaskId,
+                }, current.id),
+            };
+            return { board: replaced(board, task), task };
+        },
+        /**
+         * The task and everything under it (#285).
+         *
+         * ⚠️ Deleting cascades rather than orphaning: a subtask whose epic is gone has no place on any
+         * board, and leaving it behind under a `parentId` that names nothing is a card no view can file.
+         * The count comes back so a surface can say what it is about to do.
+         *
+         * ⚠️ The dependencies of what survives are cleaned up in the same act. A `dependsOn` pointing at
+         * a deleted task is an edge to nothing — it would draw a line into empty space in the graph view
+         * and make a task wait forever for something that cannot happen.
+         */
+        deleteTask(board, taskId) {
+            taskOf(board, taskId);
+            const removed = withDescendants(board.tasks, taskId);
+            const tasks = board.tasks
+                .filter((task) => !removed.has(task.id))
+                .map((task) => {
+                const dependsOn = task.dependsOn.filter((dependency) => !removed.has(dependency));
+                return dependsOn.length === task.dependsOn.length ? task : { ...task, dependsOn };
+            });
+            return { board: { statuses: board.statuses, tasks }, deleted: removed.size };
+        },
+        sorted,
+    };
+}

package/dist/nodes/board/board.types.d.ts

@@ -0,0 +1,31 @@
+import type { AddBoardTaskInput, BoardDocument, BoardStatusInput, BoardTask, MoveBoardTaskInput, UpdateBoardTaskInput } from "@anchrd/intel-contract";
+export interface BoardDeps {
+    id(): string;
+}
+export interface BoardPlacement {
+    status: string;
+    parentId: string | null;
+    afterTaskId: string | null;
+    beforeTaskId: string | null;
+}
+export interface BoardOperations {
+    defaultBoard(): BoardDocument;
+    configure(board: BoardDocument, statuses: BoardStatusInput[]): BoardDocument;
+    addTask(board: BoardDocument, input: AddBoardTaskInput): {
+        board: BoardDocument;
+        task: BoardTask;
+    };
+    updateTask(board: BoardDocument, input: UpdateBoardTaskInput): {
+        board: BoardDocument;
+        task: BoardTask;
+    };
+    moveTask(board: BoardDocument, input: MoveBoardTaskInput): {
+        board: BoardDocument;
+        task: BoardTask;
+    };
+    deleteTask(board: BoardDocument, taskId: string): {
+        board: BoardDocument;
+        deleted: number;
+    };
+    sorted(tasks: readonly BoardTask[]): BoardTask[];
+}

package/dist/nodes/board/board.types.js

@@ -0,0 +1 @@
+export {};

package/dist/nodes/document-links/document-links.d.ts

@@ -9,7 +9,14 @@
  * newer editor wrote; a strict parse would turn "I do not recognise this block" into "this document
  * cannot be saved". What it does not recognise contributes no link, which is the safe half.
  *
- * Content that is not a BlockNote document has no links at all: an attachment, a CSV table or plain
- * markdown carries no inline element to read.
+ * ⚠️ A board reaches the same link graph, through the same `text` origin (#285). Its links are not
+ * inline elements but the `references` of its tasks, which is a difference in where they are
+ * written and not in what they are: somebody put a node id into a body, and the graph has to see it
+ * from the other side. Reading it here rather than in the board service is what keeps ONE answer to
+ * "what does this body point at" — the writer (`reconcileTextLinks`) asks this function and does
+ * not care which kind it is holding.
+ *
+ * Content that is neither has no links at all: an attachment, a CSV table or plain markdown carries
+ * nothing to read.
  */
 export declare function documentLinkTargets(mediaType: string, content: string): string[];

package/dist/nodes/document-links/document-links.js

@@ -1,4 +1,4 @@
-import { BlockNoteDocument, BlockNoteMediaType, DocumentLinkInlineType, } from "@anchrd/intel-contract";
+import { BlockNoteDocument, BlockNoteMediaType, BoardDocument, BoardMediaType, DocumentLinkInlineType, } from "@anchrd/intel-contract";
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -30,11 +30,18 @@ function collect(value, found) {
  * newer editor wrote; a strict parse would turn "I do not recognise this block" into "this document
  * cannot be saved". What it does not recognise contributes no link, which is the safe half.
  *
- * Content that is not a BlockNote document has no links at all: an attachment, a CSV table or plain
- * markdown carries no inline element to read.
+ * ⚠️ A board reaches the same link graph, through the same `text` origin (#285). Its links are not
+ * inline elements but the `references` of its tasks, which is a difference in where they are
+ * written and not in what they are: somebody put a node id into a body, and the graph has to see it
+ * from the other side. Reading it here rather than in the board service is what keeps ONE answer to
+ * "what does this body point at" — the writer (`reconcileTextLinks`) asks this function and does
+ * not care which kind it is holding.
+ *
+ * Content that is neither has no links at all: an attachment, a CSV table or plain markdown carries
+ * nothing to read.
  */
 export function documentLinkTargets(mediaType, content) {
-    if (mediaType !== BlockNoteMediaType)
+    if (mediaType !== BlockNoteMediaType && mediaType !== BoardMediaType)
         return [];
     let parsed;
     try {
@@ -43,10 +50,20 @@ export function documentLinkTargets(mediaType, content) {
     catch {
         return [];
     }
+    const found = new Set();
+    if (mediaType === BoardMediaType) {
+        const board = BoardDocument.safeParse(parsed);
+        if (!board.success)
+            return [];
+        for (const task of board.data.tasks) {
+            for (const reference of task.references)
+                found.add(reference);
+        }
+        return [...found];
+    }
     const document = BlockNoteDocument.safeParse(parsed);
     if (!document.success)
         return [];
-    const found = new Set();
     collect(document.data.blocks, found);
     return [...found];
 }