@omnicoreos/planka-mcp 0.2.0

package/dist/errors.js

@@ -0,0 +1,226 @@
+/**
+ * Typed error classes for PLANKA API operations.
+ */
+import { z } from "zod";
+export class PlankaError extends Error {
+    code;
+    status;
+    details;
+    constructor(message, code, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = "PlankaError";
+    }
+}
+export class PlankaAuthError extends PlankaError {
+    constructor(message = "Authentication failed") {
+        super(message, "AUTH_FAILED", 401);
+        this.name = "PlankaAuthError";
+    }
+}
+export class PlankaNotFoundError extends PlankaError {
+    constructor(resource, id) {
+        super(`${resource} not found: ${id}`, "NOT_FOUND", 404);
+        this.name = "PlankaNotFoundError";
+    }
+}
+export class PlankaValidationError extends PlankaError {
+    constructor(message, details) {
+        super(message, "VALIDATION_ERROR", 422, details);
+        this.name = "PlankaValidationError";
+    }
+}
+export class PlankaPermissionError extends PlankaError {
+    constructor(message = "Insufficient permissions") {
+        super(message, "PERMISSION_DENIED", 403);
+        this.name = "PlankaPermissionError";
+    }
+}
+export class PlankaConfigError extends PlankaError {
+    constructor(message) {
+        super(message, "CONFIG_ERROR", 0);
+        this.name = "PlankaConfigError";
+    }
+}
+export class PlankaNetworkError extends PlankaError {
+    constructor(message, details) {
+        super(message, "NETWORK_ERROR", 0, details);
+        this.name = "PlankaNetworkError";
+    }
+}
+/**
+ * Factory function to create typed errors from API responses.
+ * @param status HTTP status code
+ * @param body Response body (parsed JSON or null)
+ * @param context Optional context (e.g., "GET /api/cards/123")
+ */
+export function createPlankaError(status, body, context) {
+    const message = typeof body === "object" && body !== null && "message" in body
+        ? String(body.message)
+        : "Unknown error";
+    const contextSuffix = context ? ` (${context})` : "";
+    switch (status) {
+        case 401:
+            return new PlankaAuthError(message + contextSuffix);
+        case 403:
+            return new PlankaPermissionError(message + contextSuffix);
+        case 404:
+            return new PlankaNotFoundError("Resource", context || "unknown");
+        case 422:
+            return new PlankaValidationError(message + contextSuffix, body);
+        default:
+            return new PlankaError(message + contextSuffix, "API_ERROR", status, body);
+    }
+}
+/**
+ * Type guard for PlankaError instances.
+ */
+export function isPlankaError(error) {
+    return error instanceof PlankaError;
+}
+// ---------------------------------------------------------------------------
+// Input validation — errors an agent can act on
+// ---------------------------------------------------------------------------
+/**
+ * An operation's INPUT failed validation.
+ *
+ * Deliberately NOT a subclass of PlankaError: every tool catches PlankaError
+ * to report Planka API failures, and this error has to travel untouched to the
+ * dispatcher in `src/index.ts` — the only place that knows the tool name and
+ * its inputSchema, and therefore the only place that can build the actionable
+ * message.
+ */
+export class PlankaInputError extends Error {
+    issues;
+    received;
+    constructor(issues, received) {
+        super(`Invalid input: ${issues
+            .map((issue) => `${fieldLabel(issue.path)}: ${issue.message}`)
+            .join("; ")}`);
+        this.issues = issues;
+        this.received = received;
+        this.name = "PlankaInputError";
+    }
+}
+/**
+ * Validates an operation's input against its schema.
+ * Replaces `Schema.parse(input)`: instead of a bare ZodError it throws a
+ * PlankaInputError that keeps what was received, so it can be shown back.
+ */
+export function parseInput(schema, input) {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        throw new PlankaInputError(result.error.issues, input);
+    }
+    return result.data;
+}
+/** Type guard for Zod validation errors (response-shape failures). */
+export function isZodError(error) {
+    return error instanceof z.ZodError;
+}
+const MAX_ARGS_PREVIEW = 400;
+const MAX_VALUE_PREVIEW = 120;
+/** Serializes a value for display inside an error, clipped. */
+function preview(value, max = MAX_ARGS_PREVIEW) {
+    if (value === undefined)
+        return "undefined";
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > max ? `${text.slice(0, max)}… (truncated)` : text;
+}
+/** Zod's `path: []` orients nobody; name it explicitly. */
+function fieldLabel(path) {
+    return path.length > 0 ? path.join(".") : "(whole arguments object)";
+}
+function valueAtPath(root, path) {
+    let current = root;
+    for (const key of path) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/** What the tool's JSON inputSchema declares for a field, when it declares it. */
+function propertyInfo(properties, field) {
+    const property = properties?.[field];
+    if (!property || typeof property !== "object") {
+        return { type: "", description: "" };
+    }
+    const { type, description } = property;
+    return {
+        type: typeof type === "string" ? ` (${type})` : "",
+        description: typeof description === "string" && description.length > 0
+            ? ` — ${description}`
+            : "",
+    };
+}
+/**
+ * The validation message the model sees: which tool failed, which field, what
+ * was expected and what arrived.
+ */
+export function formatInputError(toolName, error, schema) {
+    const lines = error.issues.map((issue) => {
+        const label = fieldLabel(issue.path);
+        const value = valueAtPath(error.received, issue.path);
+        const suffix = value === undefined
+            ? issue.path.length > 0
+                ? " (field missing)"
+                : " (nothing received)"
+            : ` (received: ${preview(value, MAX_VALUE_PREVIEW)})`;
+        const info = issue.path.length === 1
+            ? propertyInfo(schema?.properties, String(issue.path[0]))
+            : { type: "", description: "" };
+        return `  - ${label}${info.type}: ${issue.message}${suffix}${info.description}`;
+    });
+    const out = [`Invalid arguments for ${toolName}:`, ...lines];
+    if (schema?.required && schema.required.length > 0) {
+        out.push(`Required fields for ${toolName}: ${schema.required.join(", ")}`);
+    }
+    out.push(`Arguments received: ${preview(error.received)}`);
+    return out.join("\n");
+}
+/**
+ * Required fields that never arrived, detected before entering the handler.
+ * Without this a missing `tasks` dies as "Cannot read properties of undefined
+ * (reading 'map')", which names neither the tool nor the field.
+ */
+export function formatMissingArgsError(toolName, missing, args, schema) {
+    const out = [
+        `Invalid arguments for ${toolName}: missing required field(s): ${missing.join(", ")}.`,
+        ...missing.map((field) => {
+            const info = propertyInfo(schema?.properties, field);
+            return `  - ${field}${info.type}${info.description}`;
+        }),
+    ];
+    if (schema?.required && schema.required.length > 0) {
+        out.push(`Required fields for ${toolName}: ${schema.required.join(", ")}`);
+    }
+    out.push(`Arguments received: ${preview(args)}`);
+    return out.join("\n");
+}
+/**
+ * A ZodError that did NOT come from the input: Planka's response did not match
+ * the schema. Saying so explicitly keeps the model from assuming it got the
+ * arguments wrong.
+ */
+export function formatResponseShapeError(toolName, error) {
+    const lines = error.issues
+        .slice(0, 5)
+        .map((issue) => `  - ${fieldLabel(issue.path)}: ${issue.message}`);
+    const extra = error.issues.length > 5 ? [`  … and ${error.issues.length - 5} more`] : [];
+    return [
+        `PLANKA returned an unexpected response shape while running ${toolName}. ` +
+            `This is an API/server mismatch, not a problem with the arguments:`,
+        ...lines,
+        ...extra,
+    ].join("\n");
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/identity.generated.d.ts

@@ -0,0 +1,3 @@
+export declare const SERVER_NAME = "io.github.omnicoreos/planka-mcp";
+export declare const SERVER_VERSION = "0.2.0";
+//# sourceMappingURL=identity.generated.d.ts.map

package/dist/identity.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.generated.d.ts","sourceRoot":"","sources":["../src/identity.generated.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,oCAAoC,CAAC;AAC7D,eAAO,MAAM,cAAc,UAAU,CAAC"}

package/dist/identity.generated.js

@@ -0,0 +1,4 @@
+// Generated by scripts/sync-identity.mjs. Edit project.identity.json instead.
+export const SERVER_NAME = "io.github.omnicoreos/planka-mcp";
+export const SERVER_VERSION = "0.2.0";
+//# sourceMappingURL=identity.generated.js.map

package/dist/identity.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.generated.js","sourceRoot":"","sources":["../src/identity.generated.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,iCAAiC,CAAC;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * PLANKA MCP Server
+ *
+ * A Model Context Protocol server for PLANKA kanban boards.
+ * Provides tools for managing projects, boards, cards, tasks, labels, and comments.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getToolDefinitions, getTool, allTools, findMissingRequiredArgs, } from "./tools/index.js";
+import { PlankaError, PlankaConfigError, PlankaInputError, formatInputError, formatMissingArgsError, formatResponseShapeError, isZodError, } from "./errors.js";
+import { SERVER_NAME, SERVER_VERSION } from "./identity.generated.js";
+/** Standard error response back to the model. */
+function errorResult(text) {
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+/**
+ * Main entry point.
+ */
+async function main() {
+    // Create the MCP server
+    const server = new Server({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Handler for listing available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: getToolDefinitions(),
+        };
+    });
+    // Handler for tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const tool = getTool(name);
+        if (!tool) {
+            return errorResult(`Unknown tool: ${name}. Available tools: ${allTools
+                .map((t) => t.name)
+                .join(", ")}`);
+        }
+        // Presence check before entering the handler: a missing required field has
+        // to name the tool and the field, not die somewhere inside.
+        const missing = findMissingRequiredArgs(tool, args);
+        if (missing.length > 0) {
+            return errorResult(formatMissingArgsError(name, missing, args, tool.inputSchema));
+        }
+        try {
+            const result = await tool.handler(args || {});
+            return result;
+        }
+        catch (error) {
+            // INPUT validation: name the tool, the field and what arrived.
+            if (error instanceof PlankaInputError) {
+                return errorResult(formatInputError(name, error, tool.inputSchema));
+            }
+            // A loose ZodError means Planka's RESPONSE did not match the schema.
+            // Name it separately so the model does not assume it got the args wrong.
+            if (isZodError(error)) {
+                return errorResult(formatResponseShapeError(name, error));
+            }
+            // Handle configuration errors specifically
+            if (error instanceof PlankaConfigError) {
+                return errorResult(`Configuration error: ${error.message}\n\nRequired environment variables:\n- PLANKA_BASE_URL\n- PLANKA_AGENT_EMAIL\n- PLANKA_AGENT_PASSWORD`);
+            }
+            // Handle other PLANKA errors
+            if (error instanceof PlankaError) {
+                return errorResult(`PLANKA error: ${error.message}`);
+            }
+            // Log unexpected errors and return generic message
+            console.error(`Error in tool ${name}:`, error);
+            return errorResult(`Unexpected error while running ${name}: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    });
+    // Connect to stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log startup (to stderr so it doesn't interfere with MCP protocol)
+    console.error("PLANKA MCP server started");
+}
+// Run the server
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/operations/attachments.d.ts

@@ -0,0 +1,34 @@
+import { Attachment } from "../schemas/entities.js";
+import { AttachmentIdInput, CardIdInput, UploadAttachmentInput } from "../schemas/requests.js";
+export declare function guessMimeType(input: {
+    filePath: string;
+}): string;
+/**
+ * Get all attachments on a card (from the card endpoint's `included`).
+ */
+export declare function getAttachmentsForCard(input: CardIdInput): Promise<Attachment[]>;
+/**
+ * Upload a local file as a card attachment.
+ */
+export declare function uploadAttachment(input: UploadAttachmentInput): Promise<Attachment>;
+/**
+ * Delete an attachment.
+ */
+export declare function deleteAttachment(input: AttachmentIdInput): Promise<void>;
+/**
+ * An attachment's download URL. 2.0 exposes it as data.url; when it is
+ * missing, fall back to the /attachments/:id/download/:name pattern.
+ */
+export declare function attachmentDownloadUrl(input: {
+    attachment: Attachment;
+}): string;
+/**
+ * Download an attachment's binary content.
+ */
+export declare function downloadAttachment(input: {
+    attachment: Attachment;
+}): Promise<{
+    bytes: Uint8Array;
+    mimeType: string;
+}>;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/operations/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/operations/attachments.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAMpD,OAAO,EAEL,iBAAiB,EAEjB,WAAW,EAEX,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAmBhC,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAKjE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CAQvB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,UAAU,EAAE,UAAU,CAAC;CACxB,GAAG,MAAM,CAOT;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,UAAU,EAAE,UAAU,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAYnD"}

package/dist/operations/attachments.js

@@ -0,0 +1,89 @@
+/**
+ * Attachment operations for PLANKA API.
+ *
+ * Upload: multipart POST /api/cards/:id/attachments — both `type=file` and
+ * `name` are REQUIRED in PLANKA 2.0 (without `name` it answers 400
+ * E_MISSING_OR_INVALID_PARAMS, which reads like a permission problem).
+ */
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { plankaClient } from "../client.js";
+import { parseInput } from "../errors.js";
+import { AttachmentResponse, CardIncludedSchema, CardResponse, } from "../schemas/responses.js";
+import { AttachmentIdSchema, CardIdSchema, UploadAttachmentSchema, } from "../schemas/requests.js";
+/** MIME by extension for the usual uploads (screenshots, logs, docs). */
+const MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".log": "text/plain",
+    ".json": "application/json",
+    ".csv": "text/csv",
+    ".html": "text/html",
+};
+export function guessMimeType(input) {
+    return (MIME_BY_EXT[extname(input.filePath).toLowerCase()] ??
+        "application/octet-stream");
+}
+/**
+ * Get all attachments on a card (from the card endpoint's `included`).
+ */
+export async function getAttachmentsForCard(input) {
+    const { cardId } = parseInput(CardIdSchema, input);
+    const response = await plankaClient.get(`/api/cards/${cardId}`);
+    CardResponse.parse(response); // validates the overall shape
+    const included = CardIncludedSchema.parse(response.included || {});
+    return included.attachments || [];
+}
+/**
+ * Upload a local file as a card attachment.
+ */
+export async function uploadAttachment(input) {
+    const { cardId, filePath, name } = parseInput(UploadAttachmentSchema, input);
+    const bytes = await readFile(filePath);
+    const fileName = name ?? basename(filePath);
+    const mimeType = guessMimeType({ filePath });
+    const form = new FormData();
+    form.append("type", "file"); // required in 2.0
+    form.append("name", fileName); // required in 2.0
+    form.append("file", new Blob([new Uint8Array(bytes)], { type: mimeType }), fileName);
+    const response = await plankaClient.postMultipart(`/api/cards/${cardId}/attachments`, form);
+    return AttachmentResponse.parse(response).item;
+}
+/**
+ * Delete an attachment.
+ */
+export async function deleteAttachment(input) {
+    const { attachmentId } = parseInput(AttachmentIdSchema, input);
+    await plankaClient.delete(`/api/attachments/${attachmentId}`);
+}
+/**
+ * An attachment's download URL. 2.0 exposes it as data.url; when it is
+ * missing, fall back to the /attachments/:id/download/:name pattern.
+ */
+export function attachmentDownloadUrl(input) {
+    const { attachment } = input;
+    return (attachment.data?.url ??
+        attachment.url ??
+        `/attachments/${attachment.id}/download/${encodeURIComponent(attachment.name)}`);
+}
+/**
+ * Download an attachment's binary content.
+ */
+export async function downloadAttachment(input) {
+    const { attachment } = input;
+    const { bytes, mimeType } = await plankaClient.getBinary(attachmentDownloadUrl({ attachment }));
+    return {
+        bytes,
+        mimeType: attachment.data?.mimeType ??
+            mimeType ??
+            guessMimeType({ filePath: attachment.name }),
+    };
+}
+//# sourceMappingURL=attachments.js.map

package/dist/operations/attachments.js.map

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

package/dist/operations/board-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runs an operation that needs a boardId and, on a 404, tries to explain why
+ * instead of propagating the mute 404.
+ *
+ * `run` receives the id to use: it is invoked again with the resolved board
+ * when the id turned out to be a single-board project.
+ */
+export declare function withBoardId<T>(boardId: string, run: (id: string) => Promise<T>): Promise<T>;
+//# sourceMappingURL=board-id.d.ts.map

package/dist/operations/board-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-id.d.ts","sourceRoot":"","sources":["../../src/operations/board-id.ts"],"names":[],"mappings":"AAyFA;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,CAUZ"}

package/dist/operations/board-id.js

@@ -0,0 +1,86 @@
+/**
+ * Board id resolution: turn a bare 404 into something a model can act on.
+ *
+ * Why it exists: in Planka, project ids and board ids are both strings of
+ * digits, indistinguishable at a glance. Handing a projectId to a tool that
+ * expects a boardId gets `GET /api/boards/<projectId>` → a naked 404, and an
+ * agent burns a whole cycle discovering it picked the wrong entity.
+ *
+ * With this, that 404 becomes either:
+ *   - an automatic resolution, when the project has exactly one board; or
+ *   - an error saying "that is a projectId, and these are its boards".
+ */
+import { PlankaError, PlankaNotFoundError } from "../errors.js";
+import { getProjects } from "./projects.js";
+/** A 404 can arrive as PlankaNotFoundError or as PlankaError with status 404. */
+function isNotFound(error) {
+    if (error instanceof PlankaNotFoundError)
+        return true;
+    return error instanceof PlankaError && error.status === 404;
+}
+/** Formats `id — name` for the listings inside error messages. */
+function describe(id, name) {
+    return name ? `${id} — "${name}"` : id;
+}
+/**
+ * Diagnoses an id that failed as a board: was it actually a projectId?
+ *
+ * Returns the boardId to retry when the resolution is unambiguous (a project
+ * with exactly one board). In every other case it throws an actionable error
+ * and never returns.
+ */
+async function diagnoseBoardId(boardId) {
+    let projects;
+    let boards;
+    try {
+        ({ projects, boards } = await getProjects());
+    }
+    catch {
+        // If we cannot even list projects, the original 404 is the best
+        // information available: let the caller re-throw it.
+        throw new PlankaNotFoundError("Board", boardId);
+    }
+    const asProject = projects.find((p) => p.id === boardId);
+    if (asProject) {
+        const projectBoards = boards.filter((b) => b.projectId === asProject.id);
+        if (projectBoards.length === 1) {
+            return projectBoards[0].id;
+        }
+        if (projectBoards.length === 0) {
+            throw new PlankaError(`${boardId} is a projectId (project "${asProject.name}"), not a boardId — ` +
+                `and that project has no boards yet. Create one, or call planka_get_structure to see what exists.`, "WRONG_ENTITY_TYPE", 404);
+        }
+        const list = projectBoards
+            .map((b) => `  - ${describe(b.id, b.name)}`)
+            .join("\n");
+        throw new PlankaError(`${boardId} is a projectId (project "${asProject.name}"), not a boardId. ` +
+            `That project has ${projectBoards.length} boards — pass one of these instead:\n${list}`, "WRONG_ENTITY_TYPE", 404);
+    }
+    // Neither project nor board: show the boards that do exist, which is what
+    // the caller needs to correct itself on the next attempt.
+    const known = boards.map((b) => `  - ${describe(b.id, b.name)}`).join("\n");
+    throw new PlankaError(`No board with id ${boardId}, and it is not a projectId either. ` +
+        (boards.length
+            ? `Known boards:\n${known}\nUse planka_get_structure for the full project/board tree.`
+            : `No boards are visible to this account. Check credentials or call planka_get_structure.`), "NOT_FOUND", 404);
+}
+/**
+ * Runs an operation that needs a boardId and, on a 404, tries to explain why
+ * instead of propagating the mute 404.
+ *
+ * `run` receives the id to use: it is invoked again with the resolved board
+ * when the id turned out to be a single-board project.
+ */
+export async function withBoardId(boardId, run) {
+    try {
+        return await run(boardId);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+        // diagnoseBoardId throws unless the resolution is unambiguous.
+        const resolved = await diagnoseBoardId(boardId);
+        return await run(resolved);
+    }
+}
+//# sourceMappingURL=board-id.js.map

package/dist/operations/board-id.js.map

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