@omnicoreos/planka-mcp 0.2.0 → 0.3.0

package/dist/operations/boards.js

@@ -2,12 +2,20 @@
  * Board operations for PLANKA API.
  */
 import { plankaClient } from "../client.js";
-import { parseInput } from "../errors.js";
+import { parseInput, PlankaError } from "../errors.js";
+import { assertBoardAllowed, getPolicy } from "../config/policy.js";
 import { withBoardId } from "./board-id.js";
-import { BoardResponse, BoardIncludedSchema, CardsResponse, } from "../schemas/responses.js";
-import { BoardIdSchema, BoardSummarySchema, FindCardsSchema, GetCardsForListSchema, ListCardsSchema, } from "../schemas/requests.js";
+import { BoardResponse, BoardIncludedSchema, CardsResponse, ListResponse, } from "../schemas/responses.js";
+import { BoardIdSchema, BoardSummarySchema, FindCardsSchema, GetCardsForListSchema, ListCardsSchema, DEFAULT_DESCRIPTION_CHARS, } from "../schemas/requests.js";
 /**
  * Get a board by ID with all included entities.
+ *
+ * ⚠️ `GET /api/boards/:id` returns the cards of the FINITE lists only
+ * (`active` + `closed`). The `archive` and `trash` lists come back nameless,
+ * positionless and WITHOUT their cards. Everything derived from this call —
+ * counts, searches, summaries — is therefore a view of the visible board, not
+ * of everything Planka stores. Reads built on it flag it as
+ * `excludesArchived: true`. See docs/planka-2x-gotchas.md.
  */
 export async function getBoard(input) {
     const { boardId } = parseInput(BoardIdSchema, input);
@@ -21,8 +29,10 @@ export async function getBoard(input) {
             cards: included.cards || [],
             labels: (included.labels || []).sort((a, b) => a.position - b.position),
             cardLabels: included.cardLabels || [],
+            cardMemberships: included.cardMemberships || [],
             taskLists: (included.taskLists || []).sort((a, b) => a.position - b.position),
             tasks: included.tasks || [],
+            users: included.users || [],
         };
     });
 }
@@ -72,14 +82,17 @@ export async function getBoardWithTaskCounts(input) {
     };
 }
 /**
- * Page size of GET /api/lists/:id/cards in Planka 2.x. It is not
- * configurable: `limit` is ignored and `before` is a composite cursor
- * (`before[id]` + `before[listChangedAt]`). Verified against the live API.
+ * Page size of GET /api/lists/:id/cards in Planka 2.x — 50 at the time of
+ * writing. It is not configurable: `limit` is ignored and `before` is a
+ * composite cursor (`before[id]` + `before[listChangedAt]`).
  *
- * Without following that cursor, a column of 77 cards answers 50 and says
- * nothing about the other 27.
+ * It is NOT assumed: the first response defines it (see below). Hardcoding 50
+ * against an instance that answers 20 stops the loop on page one and reports
+ * `truncated: false` over a third of the column — the exact class of lie this
+ * module exists to avoid. The constant is kept only as the documented
+ * expectation.
  */
-const LIST_CARDS_PAGE_SIZE = 50;
+export const LIST_CARDS_EXPECTED_PAGE_SIZE = 50;
 /** Safety ceiling: 20 pages = 1000 cards. */
 const LIST_CARDS_MAX_PAGES = 20;
 export async function getCardsForList(input) {
@@ -90,6 +103,8 @@ export async function getCardsForList(input) {
     const tasks = [];
     let cursor = null;
     let truncated = false;
+    // Derived from the first response, never assumed.
+    let pageSize = null;
     for (let page = 0; page < LIST_CARDS_MAX_PAGES; page++) {
         let path = `/api/lists/${listId}/cards`;
         if (cursor) {
@@ -106,7 +121,12 @@ export async function getCardsForList(input) {
         cardLabels.push(...(included.cardLabels || []));
         taskLists.push(...(included.taskLists || []));
         tasks.push(...(included.tasks || []));
-        if (parsed.items.length < LIST_CARDS_PAGE_SIZE)
+        // An empty answer ends the list whatever the page size is.
+        if (parsed.items.length === 0)
+            break;
+        if (pageSize === null)
+            pageSize = parsed.items.length;
+        if (parsed.items.length < pageSize)
             break;
         const last = parsed.items[parsed.items.length - 1];
         if (!last.listChangedAt) {
@@ -160,6 +180,32 @@ export function normalizeText(text) {
         .replace(/[\u0300-\u036f]/g, "")
         .toLowerCase();
 }
+/**
+ * Text matching, same semantics as Planka's own `?search=`:
+ *   - a leading "/" makes the rest a case-insensitive regular expression;
+ *   - otherwise every whitespace-separated token must appear (AND), ignoring
+ *     case and accents.
+ * An invalid regex is reported to the caller instead of matching nothing.
+ */
+export function makeMatcher(query) {
+    if (query.startsWith("/")) {
+        const source = query.slice(1);
+        let regex;
+        try {
+            regex = new RegExp(source, "i");
+        }
+        catch (error) {
+            throw new PlankaError(`Invalid regular expression after "/": ${source} (${error.message}). ` +
+                `Drop the leading "/" to search for it as plain text.`, "INVALID_QUERY", 400);
+        }
+        return (haystack) => regex.test(haystack);
+    }
+    const tokens = normalizeText(query).split(/\s+/).filter(Boolean);
+    return (haystack) => {
+        const normalized = normalizeText(haystack);
+        return tokens.every((token) => normalized.includes(token));
+    };
+}
 /**
  * A board seen without its cards: just the visible lists and how many cards
  * each one holds. One GET, a handful of lines of output.
@@ -186,37 +232,15 @@ export async function getBoardListCounts(input) {
         totalCards: details.cards.length,
     };
 }
-/** Clips the description so a preview does not eat the size advantage. */
-const DESCRIPTION_PREVIEW = 200;
-function digest(card, listName, labelNames, withDescription) {
-    const description = card.description ?? null;
-    return {
-        id: card.id,
-        name: card.name,
-        listId: card.listId,
-        list: listName,
-        labels: labelNames,
-        ...(withDescription && description
-            ? {
-                description: description.length > DESCRIPTION_PREVIEW
-                    ? `${description.slice(0, DESCRIPTION_PREVIEW)}…`
-                    : description,
-            }
-            : {}),
-        ...(card.dueDate ? { dueDate: card.dueDate } : {}),
-        ...(card.isCompleted ? { isCompleted: true } : {}),
-    };
-}
-/**
- * Indexes derived from a single GET on the board: list names, label names per
- * card, and the cards ordered the way the board shows them.
- */
-async function indexBoard(boardId) {
-    const details = await getBoard({ boardId });
-    const listById = new Map(details.lists.map((l) => [l.id, l]));
-    const labelById = new Map(details.labels.map((l) => [l.id, l]));
+function indexBundle(bundle) {
+    const labelById = new Map(bundle.labels.map((l) => [l.id, l]));
+    const userById = new Map(bundle.users.map((u) => [u.id, u]));
     const labelNamesByCard = new Map();
-    for (const cl of details.cardLabels) {
+    const labelIdsByCard = new Map();
+    for (const cl of bundle.cardLabels) {
+        const ids = labelIdsByCard.get(cl.cardId) ?? [];
+        ids.push(cl.labelId);
+        labelIdsByCard.set(cl.cardId, ids);
         const label = labelById.get(cl.labelId);
         if (!label)
             continue;
@@ -224,13 +248,170 @@ async function indexBoard(boardId) {
         names.push(label.name ?? label.color);
         labelNamesByCard.set(cl.cardId, names);
     }
-    // Same order a human sees: by list position, then by card position.
+    const memberNamesByCard = new Map();
+    const memberIdsByCard = new Map();
+    for (const cm of bundle.cardMemberships) {
+        const ids = memberIdsByCard.get(cm.cardId) ?? new Set();
+        ids.add(cm.userId);
+        memberIdsByCard.set(cm.cardId, ids);
+        const names = memberNamesByCard.get(cm.cardId) ?? [];
+        names.push(userById.get(cm.userId)?.name ?? cm.userId);
+        memberNamesByCard.set(cm.cardId, names);
+    }
+    const taskListToCard = new Map(bundle.taskLists.map((tl) => [tl.id, tl.cardId]));
+    const taskCounts = new Map();
+    for (const task of bundle.tasks) {
+        const cardId = taskListToCard.get(task.taskListId);
+        if (!cardId)
+            continue;
+        const counts = taskCounts.get(cardId) ?? { total: 0, completed: 0 };
+        counts.total++;
+        if (task.isCompleted)
+            counts.completed++;
+        taskCounts.set(cardId, counts);
+        // Planka's own userIds filter matches members OR task assignees.
+        if (task.assigneeUserId) {
+            const ids = memberIdsByCard.get(cardId) ?? new Set();
+            ids.add(task.assigneeUserId);
+            memberIdsByCard.set(cardId, ids);
+        }
+    }
+    return {
+        listNameById: new Map(bundle.lists.map((l) => [l.id, l.name ?? ""])),
+        labelNamesByCard,
+        labelIdsByCard,
+        memberNamesByCard,
+        memberIdsByCard,
+        taskCounts,
+    };
+}
+/** The whole board as a bundle: one GET, every visible card. */
+async function boardBundle(boardId) {
+    const details = await getBoard({ boardId });
     const listPosition = new Map(details.lists.map((l) => [l.id, l.position ?? Number.MAX_SAFE_INTEGER]));
+    // Same order a human sees: by list position, then by card position.
     const cards = [...details.cards].sort((a, b) => {
         const byList = (listPosition.get(a.listId) ?? 0) - (listPosition.get(b.listId) ?? 0);
         return byList !== 0 ? byList : a.position - b.position;
     });
-    return { details, listById, labelById, labelNamesByCard, cards };
+    return {
+        details,
+        bundle: {
+            boardId: details.board.id,
+            cards,
+            labels: details.labels,
+            cardLabels: details.cardLabels,
+            cardMemberships: details.cardMemberships,
+            taskLists: details.taskLists,
+            tasks: details.tasks,
+            users: details.users,
+            lists: details.lists,
+            labelsResolved: true,
+        },
+    };
+}
+/**
+ * ONE list as a bundle, through `GET /api/lists/:id`: every card of the
+ * column in a single response, no cursor, no page ceiling. Label names need
+ * the board, so they cost one extra GET and only when asked for.
+ */
+async function listBundle(listId, withLabels) {
+    const response = await plankaClient.get(`/api/lists/${listId}`);
+    const list = ListResponse.parse(response).item;
+    const included = BoardIncludedSchema.parse(response.included || {});
+    // The list names its board: check that board against the allowlist before
+    // handing any of its content back.
+    assertBoardAllowed(list.boardId);
+    const cards = [...(included.cards || [])].sort((a, b) => a.position - b.position);
+    let labels = [];
+    if (withLabels) {
+        const board = await getBoard({ boardId: list.boardId });
+        labels = board.labels;
+    }
+    return {
+        list,
+        bundle: {
+            boardId: list.boardId,
+            cards,
+            labels,
+            cardLabels: included.cardLabels || [],
+            cardMemberships: included.cardMemberships || [],
+            taskLists: included.taskLists || [],
+            tasks: included.tasks || [],
+            users: included.users || [],
+            lists: [list],
+            labelsResolved: withLabels,
+        },
+    };
+}
+function clip(text, chars) {
+    return text.length > chars ? `${text.slice(0, chars)}…` : text;
+}
+function toDigest(card, index, options) {
+    const full = options.detail === "full";
+    const counts = index.taskCounts.get(card.id);
+    const members = index.memberNamesByCard.get(card.id) ?? [];
+    const description = card.description ?? null;
+    const digest = {
+        id: card.id,
+        name: card.name,
+    };
+    if (options.withListName) {
+        // Same names and same meanings as planka_get_card's `card.listId` /
+        // `card.listName`: one vocabulary across the two digests, so a match can be
+        // moved without a third call to find out where it lives. Omitted on the
+        // single-column path only because the response root already carries
+        // `list: {id, name}` — the id is never actually missing.
+        digest.listId = card.listId;
+        digest.listName = index.listNameById.get(card.listId) ?? "";
+    }
+    if (options.withLabels) {
+        // Empty arrays are omitted; the response says once, at its root, whether
+        // label names were resolved at all — so a missing `labels` is never
+        // ambiguous while still costing nothing per card.
+        const labelNames = index.labelNamesByCard.get(card.id) ?? [];
+        if (labelNames.length > 0)
+            digest.labels = labelNames;
+    }
+    // IDs travel with the names, in digest too: planka_set_card_labels takes ids
+    // and only ids, and find_cards used to publish the names alone — which sent
+    // the model back to planka_board_summary for data it already had.
+    const labelIds = index.labelIdsByCard.get(card.id) ?? [];
+    if (labelIds.length > 0)
+        digest.labelIds = labelIds;
+    if (members.length > 0)
+        digest.members = members;
+    if (counts && counts.total > 0) {
+        digest.tasks = `${counts.completed}/${counts.total}`;
+    }
+    if (card.dueDate)
+        digest.dueDate = card.dueDate;
+    if (card.commentsTotal)
+        digest.commentsTotal = card.commentsTotal;
+    if (card.updatedAt)
+        digest.updatedAt = card.updatedAt;
+    if (description !== null) {
+        if (full)
+            digest.description = description;
+        else if (options.descriptionChars > 0) {
+            digest.description = clip(description, options.descriptionChars);
+        }
+    }
+    if (full) {
+        digest.listId = card.listId;
+        digest.boardId = card.boardId;
+        digest.position = card.position;
+        digest.type = card.type;
+        digest.createdAt = card.createdAt;
+        if (card.isClosed)
+            digest.isClosed = true;
+        if (card.isDueCompleted ?? card.isDueDateCompleted) {
+            digest.isDueCompleted = true;
+        }
+    }
+    if (card.isCompleted)
+        digest.isCompleted = true;
+    return digest;
 }
 /**
  * The lists whose cards the caller asked for. Each entry matches an exact id
@@ -248,39 +429,68 @@ function selectLists(lists, wanted) {
     }
     return selected;
 }
-/**
- * Default for `cardsFrom`: the column where cards waiting on a decision pile
- * up. Matched by name so it works on any board, whatever the language.
- */
-const DECISION_LIST_HINTS = ["decision", "decide", "blocked", "bloquead"];
+/** Which `cardsFrom`/`listName` entries matched nothing at all. */
+function unmatchedHints(lists, wanted) {
+    return wanted.filter((w) => !lists.some((l) => l.name !== null &&
+        (w === l.id || normalizeText(l.name).includes(normalizeText(w)))));
+}
 /**
  * Everything needed to open a working session, in one call: columns with
- * counts, the board's labels, and the cards sitting in the column(s) waiting
- * on a decision, flagged by whether they already got one.
+ * counts, the board's labels, and — when asked — the cards of the columns
+ * named in `cardsFrom`, flagged by whether they carry `highlightLabel`.
+ *
+ * With `cardsFrom: []` (or with neither argument nor
+ * PLANKA_SUMMARY_DECISION_LISTS) it answers the shape of the board and no
+ * cards at all: that is what `planka_list_lists` now is.
  */
 export async function getBoardSummary(input) {
     const { boardId, cardsFrom, highlightLabel, limit } = parseInput(BoardSummarySchema, input);
-    const { details, listById, labelNamesByCard, cards } = await indexBoard(boardId);
+    const policy = getPolicy();
+    const { bundle, details } = await boardBundle(boardId);
+    const index = indexBundle(bundle);
+    const warnings = [];
     const countByList = new Map();
     for (const card of details.cards) {
         countByList.set(card.listId, (countByList.get(card.listId) ?? 0) + 1);
     }
     const visibleLists = details.lists.filter((list) => list.name !== null);
-    const wanted = cardsFrom ?? DECISION_LIST_HINTS;
+    const wanted = cardsFrom ?? policy.summaryDecisionLists ?? [];
     const selected = selectLists(visibleLists, wanted);
+    if (wanted.length > 0) {
+        const missed = unmatchedHints(visibleLists, wanted);
+        if (missed.length > 0) {
+            warnings.push(`cardsFrom matched no column for: ${missed.join(", ")}. Columns on this board: ` +
+                visibleLists.map((l) => l.name).join(", "));
+        }
+    }
+    const highlight = highlightLabel ?? policy.summaryHighlightLabel ?? null;
+    if (highlight !== null &&
+        !details.labels.some((l) => normalizeText(l.name ?? l.color) === normalizeText(highlight))) {
+        warnings.push(`No label named "${highlight}" on this board, so no card is highlighted. Labels: ` +
+            details.labels.map((l) => l.name ?? l.color).join(", "));
+    }
     const selectedIds = new Set(selected.map((l) => l.id));
-    const highlight = normalizeText(highlightLabel);
-    const matching = cards
-        .filter((card) => selectedIds.has(card.listId))
-        .map((card) => {
-        const labels = labelNamesByCard.get(card.id) ?? [];
-        return {
-            ...digest(card, listById.get(card.listId)?.name ?? "", labels, false),
-            highlighted: labels.some((l) => normalizeText(l) === highlight),
-        };
-    });
+    const options = {
+        detail: "digest",
+        descriptionChars: 0,
+        withLabels: true,
+        withListName: true,
+    };
+    const matching = selectedIds.size === 0
+        ? []
+        : bundle.cards
+            .filter((card) => selectedIds.has(card.listId))
+            .map((card) => {
+            const labels = index.labelNamesByCard.get(card.id) ?? [];
+            const digest = toDigest(card, index, options);
+            return highlight !== null &&
+                labels.some((l) => normalizeText(l) === normalizeText(highlight))
+                ? { ...digest, highlighted: true }
+                : digest;
+        });
     // Unblocked first: that is what gets picked up at the start of a session.
-    matching.sort((a, b) => Number(b.highlighted) - Number(a.highlighted));
+    matching.sort((a, b) => Number("highlighted" in b && b.highlighted) -
+        Number("highlighted" in a && a.highlighted));
     const page = matching.slice(0, limit);
     return {
         board: details.board,
@@ -291,77 +501,151 @@ export async function getBoardSummary(input) {
             cardCount: countByList.get(list.id) ?? 0,
         })),
         labels: details.labels.map((l) => ({ id: l.id, name: l.name ?? l.color })),
-        highlightLabel,
+        totalCards: details.cards.length,
+        ...(highlight !== null ? { highlightLabel: highlight } : {}),
         cardsFrom: selected.map((l) => l.name ?? l.id),
         cards: page,
         highlightedCount: matching.filter((c) => c.highlighted).length,
         returned: page.length,
         total: matching.length,
         hasMore: page.length < matching.length,
+        warnings,
     };
 }
 /**
- * Searches a board's cards by label and/or text. Text matches both name and
- * description, case- and accent-insensitive.
+ * The one search over a board's cards.
+ *
+ * With `listId` it reads that column alone (`GET /api/lists/:id`): one call,
+ * unpaginated, so `total` is the real size of the column and nothing can be
+ * silently clipped. Without it, it filters over a single board read.
  */
 export async function findCards(input) {
-    const { boardId, labelName, query, listId, withDescription, limit, offset } = parseInput(FindCardsSchema, input);
-    const { details, listById, labelById, labelNamesByCard, cards } = await indexBoard(boardId);
+    const params = parseInput(FindCardsSchema, input);
+    const { boardId, listId, listName, labelIds, userIds, query, withLabels, detail, limit, offset, } = params;
+    const labelName = params.labelName ?? params.labelFilter;
     const warnings = [];
+    const descriptionChars = params.descriptionChars ??
+        (params.withDescription ? DEFAULT_DESCRIPTION_CHARS : 0);
+    // Label names are needed for the filter, and for anything but a bare digest.
+    const needLabels = withLabels || labelName !== undefined || detail === "full";
+    let bundle;
+    let scopedList = null;
+    let source;
+    let listIdsFilter = null;
+    if (listId) {
+        const read = await listBundle(listId, needLabels);
+        bundle = read.bundle;
+        scopedList = read.list;
+        source = "list";
+    }
+    else {
+        const read = await boardBundle(boardId);
+        bundle = read.bundle;
+        source = "board";
+        if (listName) {
+            const hits = selectLists(bundle.lists, [listName]);
+            if (hits.length === 0) {
+                warnings.push(`No column matching "${listName}" on this board. Columns: ` +
+                    bundle.lists
+                        .filter((l) => l.name !== null)
+                        .map((l) => l.name)
+                        .join(", "));
+            }
+            if (hits.length === 1)
+                scopedList = hits[0];
+            listIdsFilter = new Set(hits.map((l) => l.id));
+        }
+    }
+    const index = indexBundle(bundle);
     // labelName -> ids. A board can carry the same name on two labels.
-    let labelIds = null;
+    let labelNameIds = null;
     if (labelName) {
+        if (!bundle.labelsResolved) {
+            // Cannot happen through the tools (needLabels covers it), but a direct
+            // caller must not get a silent zero.
+            throw new PlankaError("labelName needs the board's labels; do not pass withLabels: false with it.", "INVALID_ARGUMENTS", 400);
+        }
         const wanted = normalizeText(labelName);
-        const hits = details.labels.filter((l) => normalizeText(l.name ?? l.color) === wanted);
+        const hits = bundle.labels.filter((l) => normalizeText(l.name ?? l.color) === wanted);
         if (hits.length === 0) {
             warnings.push(`No label named "${labelName}" on this board. Existing labels: ` +
-                details.labels.map((l) => l.name ?? l.color).join(", "));
+                bundle.labels.map((l) => l.name ?? l.color).join(", "));
         }
-        labelIds = new Set(hits.map((l) => l.id));
-    }
-    if (listId && !listById.has(listId)) {
-        warnings.push(`No list ${listId} on this board.`);
+        labelNameIds = new Set(hits.map((l) => l.id));
     }
-    const needle = query ? normalizeText(query) : null;
-    const matched = cards.filter((card) => {
-        if (listId && card.listId !== listId)
+    const wantedLabelIds = labelIds ? new Set(labelIds) : null;
+    const wantedUserIds = userIds ? new Set(userIds) : null;
+    const matches = query ? makeMatcher(query) : null;
+    const matched = bundle.cards.filter((card) => {
+        if (listIdsFilter && !listIdsFilter.has(card.listId))
+            return false;
+        const cardLabelIds = index.labelIdsByCard.get(card.id) ?? [];
+        if (labelNameIds && !cardLabelIds.some((id) => labelNameIds.has(id))) {
+            return false;
+        }
+        if (wantedLabelIds && !cardLabelIds.some((id) => wantedLabelIds.has(id))) {
             return false;
-        if (labelIds) {
-            const cardLabelIds = details.cardLabels
-                .filter((cl) => cl.cardId === card.id)
-                .map((cl) => cl.labelId);
-            if (!cardLabelIds.some((id) => labelIds.has(id)))
-                return false;
         }
-        if (needle) {
-            const haystack = normalizeText(`${card.name}\n${card.description ?? ""}`);
-            if (!haystack.includes(needle))
+        if (wantedUserIds) {
+            const cardUserIds = index.memberIdsByCard.get(card.id);
+            if (!cardUserIds)
                 return false;
+            let hit = false;
+            for (const id of cardUserIds)
+                if (wantedUserIds.has(id))
+                    hit = true;
+            if (!hit)
+                return false;
+        }
+        if (matches && !matches(`${card.name}\n${card.description ?? ""}`)) {
+            return false;
         }
         return true;
     });
     const page = matched.slice(offset, offset + limit);
     const hasMore = offset + page.length < matched.length;
+    // The column name is hoisted out of every card when they all share it.
+    const singleColumn = source === "list" || (listIdsFilter !== null && listIdsFilter.size === 1);
+    const options = {
+        detail,
+        descriptionChars,
+        withLabels: needLabels,
+        withListName: !singleColumn,
+    };
     return {
-        boardId,
+        boardId: bundle.boardId,
+        ...(scopedList
+            ? { list: { id: scopedList.id, name: scopedList.name } }
+            : {}),
         filters: {
+            ...(listId ? { listId } : {}),
+            ...(listName ? { listName } : {}),
             ...(labelName ? { labelName } : {}),
+            ...(labelIds ? { labelIds } : {}),
+            ...(userIds ? { userIds } : {}),
             ...(query ? { query } : {}),
-            ...(listId ? { listId } : {}),
         },
+        detail,
+        source,
+        labelsResolved: needLabels,
+        ...(source === "list" ? { truncated: false } : {}),
+        ...(source === "board" ? { excludesArchived: true } : {}),
         total: matched.length,
         returned: page.length,
         offset,
         hasMore,
         ...(hasMore ? { nextOffset: offset + page.length } : {}),
-        matches: page.map((card) => digest(card, listById.get(card.listId)?.name ?? "", labelNamesByCard.get(card.id) ?? [], withDescription)),
-        ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}),
+        matches: page.map((card) => toDigest(card, index, options)),
+        warnings,
     };
 }
 /**
- * Cards of ONE list, paginated outward. `limit`/`offset` are output-side:
- * Planka's API accepts neither, so the whole list is resolved through its
- * cursor and clipped here — the only way to report an honest `total`.
+ * Cards of ONE list, paginated outward, through the cursor of
+ * `GET /api/lists/:id/cards`.
+ *
+ * Kept for callers that want the raw card records; `planka_list_cards` no
+ * longer goes through here — it is an alias of findCards({ listId }), which
+ * gets the same cards in ONE request via the list show.
  */
 export async function listCards(input) {
     const { listId, withLabels, labelFilter, limit, offset } = parseInput(ListCardsSchema, input);