@kietdev/taiga-mcp 0.0.0-stage → 0.4.0

package/dist/taiga/client.js

@@ -0,0 +1,1274 @@
+import { fold, progress } from '../format.js';
+import { TaigaError, TaigaHttp } from './http.js';
+import { readFile } from './files.js';
+export { TaigaError } from './http.js';
+/** Where each kind of item lives in Taiga's API, and what Taiga calls it elsewhere. */
+const API = {
+    story: {
+        list: '/userstories',
+        history: 'userstory',
+        label: 'user story',
+        resolved: 'us',
+        finished: 'finish_date',
+    },
+    issue: { list: '/issues', history: 'issue', label: 'issue', resolved: 'issue', finished: 'finished_date' },
+    epic: { list: '/epics', history: 'epic', label: 'epic', resolved: 'epic', finished: undefined },
+    task: { list: '/tasks', history: 'task', label: 'task', resolved: 'task', finished: 'finished_date' },
+};
+const KINDS = Object.keys(API);
+/** What `assigned_to` may say for "assigned to nobody". */
+const UNASSIGNED = new Set(['unassigned', 'nobody', 'no one', 'none']);
+/** What `assigned_to` may say for the signed-in user. */
+const ME = new Set(['me', 'myself']);
+/** A comment shown back in the answer is cut to this many characters. */
+const COMMENT_ECHO = 300;
+/** An error that lists every member is no help in a project of hundreds. */
+const MEMBERS_LISTED = 40;
+/** Statuses and sprints change rarely; one question to the model often needs the project several times. */
+const PROJECT_CACHE_MS = 60_000;
+const COMMENTS_SHOWN = 5;
+const CHANGES_SHOWN = 20;
+/** Activity is read 100 events at a time, newest first, and at most this many times per question. */
+const ACTIVITY_BATCH = 100;
+const ACTIVITY_BATCHES = 10;
+/** The largest file read; a hosted server must also fit the answer in its response. */
+export const FILE_MAX_BYTES = 10 * 1024 * 1024;
+/** Images go to the model as they are, base64 in the answer, so they are held to less. */
+export const IMAGE_MAX_BYTES = 3 * 1024 * 1024;
+/** Fields of a history entry that say nothing a reader wants: positions on a board, and what the status already tells. */
+const SILENT_CHANGES = new Set([
+    'is_closed',
+    'finish_date',
+    'finished_date',
+    'description_html',
+    'blocked_note_html',
+]);
+const optional = (value, use) => value === undefined ? undefined : use(value);
+const same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+const article = (label) => (/^[aei]/.test(label) ? `an ${label}` : `a ${label}`);
+const day = (timestamp) => timestamp?.slice(0, 10);
+/** Today as YYYY-MM-DD in the machine's own time zone, which is how sprint dates are meant. */
+function localDay(date) {
+    const two = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${two(date.getMonth() + 1)}-${two(date.getDate())}`;
+}
+/**
+ * Files already read, by the checksum of their content, so that reading a large file a part at a
+ * time downloads and parses it once. Keyed by content, the cache cannot hand anyone a file they
+ * could not read: only someone who can see a file with that checksum asks for it.
+ */
+class FileCache {
+    ttlMs;
+    maxBytes;
+    #entries = new Map();
+    #size = 0;
+    constructor(ttlMs, maxBytes) {
+        this.ttlMs = ttlMs;
+        this.maxBytes = maxBytes;
+    }
+    get(key, now) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (now - entry.at > this.ttlMs) {
+            this.#drop(key);
+            return undefined;
+        }
+        return entry.content;
+    }
+    set(key, content, size, now) {
+        if (size > this.maxBytes)
+            return;
+        this.#drop(key);
+        this.#entries.set(key, { at: now, size, content });
+        this.#size += size;
+        // A Map keeps insertion order: the first entries are the oldest.
+        for (const old of this.#entries.keys()) {
+            if (this.#size <= this.maxBytes)
+                break;
+            this.#drop(old);
+        }
+    }
+    clear() {
+        this.#entries.clear();
+        this.#size = 0;
+    }
+    #drop(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return;
+        this.#size -= entry.size;
+        this.#entries.delete(key);
+    }
+}
+const fileCache = new FileCache(10 * 60_000, 64 * 1024 * 1024);
+/** For tests: forget every file read so far. */
+export function forgetFiles() {
+    fileCache.clear();
+}
+/**
+ * What the tools ask Taiga, in the tools' own terms: project slugs, status names and reference
+ * numbers go in, trimmed summaries come out. Ids never leave this class.
+ */
+export class TaigaClient {
+    #http;
+    #baseUrl;
+    #now;
+    #projects = new Map();
+    #me;
+    constructor(config, fetchImpl = fetch, now = () => new Date()) {
+        this.#http = new TaigaHttp(config, fetchImpl);
+        this.#baseUrl = config.baseUrl;
+        this.#now = now;
+    }
+    /** Whether this connection may create and change items. */
+    get writable() {
+        return this.#http.writable;
+    }
+    async currentUser() {
+        this.#me ??= await this.#http.get('/users/me');
+        return this.#me;
+    }
+    /** The projects the signed-in user is a member of, by name. */
+    async listProjects() {
+        const me = await this.currentUser();
+        const projects = await this.#http.get('/projects', { member: me.id }, { everything: true });
+        return projects
+            .map((project) => ({
+            id: project.id,
+            name: project.name,
+            slug: project.slug,
+            isPrivate: project.is_private ?? false,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /** Sprints, newest first. Open ones unless `closed` is true. */
+    async listSprints(slug, options) {
+        const project = await this.#project(slug);
+        const { items, total } = await this.#http.page('/milestones', { project: project.id, closed: options.closed ?? false }, options.limit, options.page);
+        const today = localDay(this.#now());
+        return { project: project.name, total, items: items.map((sprint) => toSprint(sprint, today)) };
+    }
+    /** User stories in board order. */
+    async listUserStories(slug, filters) {
+        const project = await this.#project(slug);
+        const sprint = filters.sprint === undefined ? undefined : await this.#sprintFilter(project, filters.sprint, 'story');
+        const epic = filters.epic === undefined
+            ? undefined
+            : await this.#idOf(project, filters.epic, 'epic', 'Call list_epics for the epic numbers.');
+        const common = await this.#commonFilters(project, 'story', filters);
+        const { items, total } = await this.#http.page(API.story.list, { ...common.query, ...sprint?.query, epic }, filters.limit, filters.page);
+        return {
+            project: project.name,
+            assignee: common.assignee,
+            sprint: sprint?.label,
+            total,
+            items: items.map((story) => ({
+                ...toSummary(story),
+                sprint: story.milestone_name ?? undefined,
+                points: story.total_points ?? undefined,
+                finished: day(story.finish_date ?? undefined),
+            })),
+        };
+    }
+    /** Issues, most recently created first. */
+    async listIssues(slug, filters) {
+        const project = await this.#project(slug);
+        const common = await this.#commonFilters(project, 'issue', filters);
+        const query = {
+            ...common.query,
+            type: optional(filters.type, (name) => find(project, project.issueTypes, name, 'issue type')),
+            severity: optional(filters.severity, (name) => find(project, project.severities, name, 'severity')),
+            priority: optional(filters.priority, (name) => find(project, project.priorities, name, 'priority')),
+            order_by: '-created_date',
+        };
+        const { items, total } = await this.#http.page(API.issue.list, query, filters.limit, filters.page);
+        return {
+            project: project.name,
+            assignee: common.assignee,
+            total,
+            items: items.map((issue) => ({
+                ...toSummary(issue),
+                ...issueNames(project, issue),
+                finished: day(issue.finished_date ?? undefined),
+            })),
+        };
+    }
+    /** Epics in board order, each with how many of its stories are done. */
+    async listEpics(slug, filters) {
+        const project = await this.#project(slug);
+        const common = await this.#commonFilters(project, 'epic', filters);
+        const { items, total } = await this.#http.page(API.epic.list, common.query, filters.limit, filters.page);
+        return {
+            project: project.name,
+            assignee: common.assignee,
+            total,
+            items: items.map((epic) => ({
+                ...toSummary(epic),
+                stories: epic.user_stories_counts?.total ?? 0,
+                storiesDone: epic.user_stories_counts?.progress ?? 0,
+            })),
+        };
+    }
+    /** Tasks, the small pieces of work inside a user story. */
+    async listTasks(slug, filters) {
+        const project = await this.#project(slug);
+        const sprint = filters.sprint === undefined ? undefined : await this.#sprintFilter(project, filters.sprint, 'task');
+        const story = filters.story === undefined
+            ? undefined
+            : await this.#idOf(project, filters.story, 'story', 'Call list_user_stories for the story numbers.');
+        const common = await this.#commonFilters(project, 'task', filters);
+        const { items, total } = await this.#http.page(API.task.list, { ...common.query, ...sprint?.query, user_story: story }, filters.limit, filters.page);
+        return {
+            project: project.name,
+            assignee: common.assignee,
+            sprint: sprint?.label,
+            total,
+            items: items.map((task) => toTask(project, task)),
+        };
+    }
+    /**
+     * One story, issue, epic or task by its reference number. Taiga numbers all four from one
+     * sequence per project, so the number alone says which kind it is.
+     */
+    async getItem(slug, ref, options = {}) {
+        const project = await this.#project(slug);
+        const { kind, id } = await this.#resolve(project, ref);
+        if (kind === undefined) {
+            throw new TaigaError(`Project "${project.name}" has no item #${ref}. Use a list tool to find the reference number.`, 404);
+        }
+        const api = API[kind];
+        const fields = project.customFields[kind];
+        const commentsWanted = options.comments ?? COMMENTS_SHOWN;
+        const changesPage = options.changesPage ?? 1;
+        const historyPath = `/history/${api.history}/${id}`;
+        const [item, custom, history, activity, tasks, attachments] = await Promise.all([
+            this.#http.get(`${api.list}/${id}`),
+            // Most projects define no custom fields: skip the request then.
+            fields.length === 0
+                ? undefined
+                : this.#http.get(`${api.list}/custom-attributes-values/${id}`),
+            // A deleted comment stays in the history, so ask for a few more than are shown.
+            commentsWanted === 0
+                ? undefined
+                : this.#http.page(historyPath, { type: 'comment' }, commentsWanted * 2),
+            options.changes || options.changesPage !== undefined
+                ? this.#http
+                    .page(historyPath, { type: 'activity' }, CHANGES_SHOWN, changesPage)
+                    .catch((error) => {
+                    if (changesPage > 1 && error instanceof TaigaError && error.status === 404) {
+                        throw new TaigaError(`The history of #${ref} has no page ${changesPage}. Call with \`changes_page\`: 1 to see how many pages there are.`, 404);
+                    }
+                    throw error;
+                })
+                : undefined,
+            kind === 'story'
+                ? this.#http.get(API.task.list, { project: project.id, user_story: id }, { everything: true })
+                : undefined,
+            this.#attachments(api.list, project, id),
+        ]);
+        const deleted = history?.items.filter((entry) => entry.delete_comment_date).length ?? 0;
+        const comments = history?.items
+            .filter((entry) => entry.comment && !entry.delete_comment_date)
+            .slice(0, commentsWanted)
+            .map((entry) => ({
+            author: authorOf(entry),
+            date: day(entry.created_at) ?? '',
+            text: entry.comment ?? '',
+        }));
+        const changes = activity?.items.flatMap((entry) => {
+            const what = describeChange(entry.values_diff ?? {});
+            return what === undefined ? [] : [{ author: authorOf(entry), date: day(entry.created_at) ?? '', what }];
+        });
+        return {
+            ...toSummary(item),
+            kind,
+            project: project.name,
+            description: item.description?.trim() ?? '',
+            createdBy: item.owner_extra_info?.full_name_display,
+            created: day(item.created_date),
+            modified: day(item.modified_date),
+            blockedNote: item.is_blocked ? item.blocked_note?.trim() || 'no reason given' : undefined,
+            tags: (item.tags ?? []).map(tagName),
+            facts: factsOf(kind, project, item),
+            customFields: fields.flatMap((field) => {
+                const value = custom?.attributes_values?.[String(field.id)];
+                return value === undefined || value === null || value === ''
+                    ? []
+                    : [[field.name, String(value)]];
+            }),
+            comments,
+            totalComments: Math.max((history?.total ?? 0) - deleted, comments?.length ?? 0),
+            tasks: tasks?.map((task) => toTask(project, task)),
+            attachments,
+            changes,
+            totalChanges: Math.max(activity?.total ?? 0, changes?.length ?? 0),
+            changesPage,
+            changesPages: Math.max(1, Math.ceil((activity?.total ?? 0) / CHANGES_SHOWN)),
+            version: item.version,
+        };
+    }
+    /**
+     * The text or image of one file attached to an item. `file` is its number in the item's list
+     * of files, or its name (or a part of it that fits one file only).
+     */
+    async getAttachment(slug, ref, file) {
+        const project = await this.#project(slug);
+        const { kind, id } = await this.#resolve(project, ref);
+        if (kind === undefined || id === undefined) {
+            throw new TaigaError(`Project "${project.name}" has no item #${ref}.`, 404);
+        }
+        const files = await this.#attachments(API[kind].list, project, id);
+        const label = `${API[kind].label} #${ref}`;
+        if (files.length === 0)
+            throw new TaigaError(`${capital(label)} has no attached files.`, 404);
+        const wanted = file.trim();
+        const byNumber = /^#?\d+$/.test(wanted) ? files[Number(wanted.replace('#', '')) - 1] : undefined;
+        const exact = files.filter((f) => same(f.name, wanted));
+        const partial = files.filter((f) => f.name.toLowerCase().includes(wanted.toLowerCase()));
+        const found = byNumber ?? (exact.length === 1 ? exact[0] : partial.length === 1 ? partial[0] : undefined);
+        if (found === undefined) {
+            const list = files.map((f) => `${f.number}. ${f.name}`).join(', ');
+            throw new TaigaError(partial.length > 1
+                ? `"${file}" fits several files of ${label}: ${list}. Pass the number.`
+                : `${capital(label)} has no file "${file}". Its files: ${list}.`, 404);
+        }
+        if (found.url === undefined)
+            throw new TaigaError(`Taiga gave no address for "${found.name}".`);
+        const now = this.#now().getTime();
+        const cached = found.sha1 === undefined ? undefined : fileCache.get(found.sha1, now);
+        if (cached !== undefined)
+            return { item: `${capital(label)} of ${project.name}`, file: found, content: cached };
+        const { bytes, type } = await this.#http.download(found.url, FILE_MAX_BYTES);
+        let content = await readFile(found.name, bytes, type);
+        if (content.kind === 'image' && bytes.byteLength > IMAGE_MAX_BYTES) {
+            content = {
+                kind: 'unreadable',
+                reason: `The image is ${(bytes.byteLength / (1024 * 1024)).toFixed(1)} MB; images are passed on up to ${IMAGE_MAX_BYTES / (1024 * 1024)} MB. Open it in Taiga instead.`,
+            };
+        }
+        if (found.sha1 !== undefined)
+            fileCache.set(found.sha1, content, bytes.byteLength, now);
+        return { item: `${capital(label)} of ${project.name}`, file: found, content };
+    }
+    /* ------------------------------- activity ------------------------------- */
+    /**
+     * What happened in a project, newest first: items created, changed, commented on, deleted.
+     * Taiga can only list activity from the newest event backwards, so filters are applied while
+     * reading, up to ACTIVITY_BATCHES batches; the answer says how far back it looked.
+     */
+    async listActivity(slug, filters) {
+        const project = await this.#project(slug);
+        if (filters.byMe && filters.by !== undefined) {
+            throw new TaigaError('Pass either `by_me` or `by`, not both.');
+        }
+        const who = filters.byMe
+            ? { id: (await this.currentUser()).id, label: 'me' }
+            : filters.by === undefined
+                ? undefined
+                : (({ id, name }) => ({ id, label: name }))(findMember(project, filters.by));
+        // A person's own activity is a much shorter list to go through than the whole project's.
+        const path = who === undefined ? `/timeline/project/${project.id}` : `/timeline/user/${who.id}`;
+        const page = filters.page ?? 1;
+        const skip = (page - 1) * filters.limit;
+        const until = optional(filters.to, endOfDay);
+        const matches = [];
+        let newest;
+        let oldest;
+        let complete = false;
+        reading: for (let batch = 1; batch <= ACTIVITY_BATCHES; batch++) {
+            let events;
+            try {
+                events = (await this.#http.page(path, {}, ACTIVITY_BATCH, batch)).items;
+            }
+            catch (error) {
+                // Past the last page: everything has been read.
+                if (batch > 1 && error instanceof TaigaError && error.status === 404) {
+                    complete = true;
+                    break;
+                }
+                throw error;
+            }
+            for (const event of events) {
+                newest ??= event.created;
+                oldest = event.created;
+                if (until !== undefined && event.created > until)
+                    continue;
+                if (filters.from !== undefined && event.created < filters.from) {
+                    complete = true;
+                    break reading;
+                }
+                if (event.data?.project?.id !== undefined && event.data.project.id !== project.id)
+                    continue;
+                const activity = describeEvent(event, filters);
+                if (activity === undefined)
+                    continue;
+                matches.push(activity);
+                // One more than asked for says whether there are more.
+                if (matches.length > skip + filters.limit)
+                    break reading;
+            }
+            if (events.length < ACTIVITY_BATCH) {
+                complete = true;
+                break;
+            }
+        }
+        return {
+            project: project.name,
+            by: who?.label,
+            items: matches.slice(skip, skip + filters.limit),
+            first: skip + 1,
+            more: matches.length > skip + filters.limit,
+            checkedBackTo: complete || matches.length > skip + filters.limit ? undefined : day(oldest),
+            logEndsOn: logEnd(newest, filters.from, this.#now()),
+        };
+    }
+    /* -------------------------------- sprints -------------------------------- */
+    /** One sprint in full: progress by stories, tasks and points, and the burndown. */
+    async getSprint(slug, wanted) {
+        const project = await this.#project(slug);
+        const sprint = await this.#findSprint(project, wanted);
+        const [detail, stats] = await Promise.all([
+            this.#http.get(`/milestones/${sprint.id}`),
+            this.#http.get(`/milestones/${sprint.id}/stats`),
+        ]);
+        const today = localDay(this.#now());
+        const summary = toSprint(detail, today);
+        const sum = (value) => typeof value === 'number'
+            ? value
+            : Object.values(value ?? {}).reduce((a, b) => a + (b ?? 0), 0);
+        const done = stats.completed_points;
+        const points = Math.max(sum(stats.total_points), summary.totalPoints);
+        return {
+            project: project.name,
+            name: summary.name,
+            start: summary.start,
+            finish: summary.finish,
+            closed: summary.closed,
+            current: summary.current,
+            stories: summary.stories,
+            storiesDone: summary.storiesDone,
+            tasks: stats.total_tasks ?? 0,
+            tasksDone: stats.completed_tasks ?? 0,
+            points,
+            pointsDone: Math.max(typeof done === 'number' ? done : (done ?? []).reduce((a, b) => a + (b ?? 0), 0), summary.closedPoints),
+            iocaineDoses: stats.iocaine_doses ?? 0,
+            burndown: points === 0
+                ? []
+                : (stats.days ?? [])
+                    .filter((d) => d.day <= today)
+                    .map((d) => ({
+                    day: d.day,
+                    open: round(d.open_points ?? 0),
+                    ideal: round(d.optimal_points ?? 0),
+                })),
+        };
+    }
+    /** A sprint by name, or the one running today. */
+    async #findSprint(project, wanted) {
+        const named = project.sprints.find((sprint) => same(sprint.name, wanted) || same(sprint.slug, wanted));
+        if (named !== undefined)
+            return named;
+        if (!same(wanted, 'current')) {
+            throw new TaigaError(`Project "${project.name}" has no sprint "${wanted}". Pass a sprint name from list_sprints, or "current".`);
+        }
+        return this.#currentSprint(project);
+    }
+    /** The files attached to an item. An item the user may read but whose files they may not is shown without them. */
+    async #attachments(list, project, id) {
+        const raw = await this.#http
+            .get(`${list}/attachments`, { project: project.id, object_id: id }, { everything: true })
+            .catch((error) => {
+            if (error instanceof TaigaError && (error.status === 403 || error.status === 404))
+                return [];
+            throw error;
+        });
+        return raw
+            .filter((file) => !file.is_deprecated)
+            .map((file, i) => ({
+            number: i + 1,
+            name: file.name,
+            size: file.size ?? undefined,
+            url: file.url ?? undefined,
+            note: file.description?.trim() || undefined,
+            sha1: file.sha1 || undefined,
+        }));
+    }
+    /* -------------------------------- project -------------------------------- */
+    /** The people of a project and the names its items use: statuses, severities, tags… */
+    async getProject(slug) {
+        const project = await this.#project(slug);
+        const { sprints, customFields } = project;
+        return {
+            name: project.name,
+            slug: project.slug,
+            description: project.description,
+            isPrivate: project.isPrivate,
+            modules: project.modules,
+            members: project.members,
+            statuses: project.statuses,
+            severities: project.severities,
+            priorities: project.priorities,
+            issueTypes: project.issueTypes,
+            tags: project.tags,
+            customFields: {
+                story: customFields.story.map((field) => field.name),
+                issue: customFields.issue.map((field) => field.name),
+                epic: customFields.epic.map((field) => field.name),
+                task: customFields.task.map((field) => field.name),
+            },
+            openSprints: sprints.filter((sprint) => !sprint.closed).length,
+            closedSprints: sprints.filter((sprint) => sprint.closed).length,
+        };
+    }
+    /* ---------------------------------- wiki ---------------------------------- */
+    /** The wiki pages of a project, most recently changed first. */
+    async listWikiPages(slug, paging) {
+        const project = await this.#project(slug);
+        const [pages, links] = await Promise.all([
+            this.#http.page('/wiki', { project: project.id, order_by: '-modified_date' }, paging.limit, paging.page),
+            this.#wikiLinks(project),
+        ]);
+        return {
+            project: project.name,
+            total: pages.total,
+            items: pages.items.map((page) => toWikiSummary(page, links)),
+        };
+    }
+    /** One wiki page, by its slug or by its title in the wiki's menu. */
+    async getWikiPage(slug, page) {
+        const project = await this.#project(slug);
+        const links = await this.#wikiLinks(project);
+        const wanted = links.find((link) => same(link.title, page))?.href ?? page.trim().toLowerCase();
+        const raw = await this.#http
+            .get('/wiki/by_slug', { project: project.id, slug: wanted })
+            .catch((error) => {
+            if (error instanceof TaigaError && error.status === 404) {
+                throw new TaigaError(`Project "${project.name}" has no wiki page "${page}". Call list_wiki_pages to see the pages.`, 404);
+            }
+            throw error;
+        });
+        return {
+            ...toWikiSummary(raw, links),
+            project: project.name,
+            content: raw.content?.trim() ?? '',
+            created: day(raw.created_date),
+            modifiedBy: project.members.find((member) => member.id === raw.last_modifier)?.name,
+        };
+    }
+    /** The wiki pages whose text contains the words. */
+    async searchWiki(slug, words) {
+        const project = await this.#project(slug);
+        const [found, links] = await Promise.all([
+            this.#http.get('/search', { project: project.id, text: words.trim() }),
+            this.#wikiLinks(project),
+        ]);
+        return (found.wikipages ?? []).map((page) => toWikiSummary(page, links));
+    }
+    #wikiLinks(project) {
+        return this.#http.get('/wiki-links', { project: project.id }, { everything: true });
+    }
+    /* ------------------------------ projects ------------------------------ */
+    /** The project behind a slug, remembered for a minute. */
+    /* -------------------------------- writes -------------------------------- */
+    /** Add a comment to a story, issue, epic or task. */
+    async addComment(slug, ref, text) {
+        const comment = text.trim();
+        if (comment === '')
+            throw new TaigaError('The comment is empty: pass the text to post.');
+        const { project, kind, id, current } = await this.#current(slug, ref);
+        // A comment changes no field, so the version read just now can never conflict.
+        const updated = await this.#http.write('PATCH', `${API[kind].list}/${id}`, {
+            comment,
+            version: current.version,
+        });
+        return {
+            ...this.#written(project, kind, updated),
+            changed: [],
+            facts: [['Comment', truncateText(comment, COMMENT_ECHO)]],
+        };
+    }
+    /** Create a user story, task or issue. Every name is checked before anything is sent. */
+    async createItem(slug, input) {
+        const project = await this.#project(slug);
+        const { kind } = input;
+        const subject = input.subject.trim();
+        if (subject === '')
+            throw new TaigaError('The title is empty: pass a `subject`.');
+        const only = (given, field, kinds) => {
+            if (given !== undefined)
+                throw new TaigaError(`\`${field}\` is for ${kinds} only.`);
+        };
+        if (kind !== 'task')
+            only(input.story, 'story', 'tasks');
+        if (kind === 'task' && input.story === undefined && input.sprint === undefined) {
+            // Taiga shows a task on the taskboard of a sprint or under its story; with neither, nobody sees it.
+            throw new TaigaError('A task needs a user story (`story`) or a sprint (`sprint`), or it appears on no board. ' +
+                'For work that belongs to no story, create a user story or an issue instead.');
+        }
+        if (kind !== 'story')
+            only(input.epic, 'epic', 'user stories');
+        if (kind !== 'issue') {
+            only(input.type, 'type', 'issues');
+            only(input.severity, 'severity', 'issues');
+            only(input.priority, 'priority', 'issues');
+        }
+        const body = { project: project.id, subject };
+        if (input.description?.trim())
+            body['description'] = input.description;
+        if (input.status !== undefined) {
+            body['status'] = find(project, project.statuses[kind], input.status, `${API[kind].label} status`);
+        }
+        if (input.assignedTo !== undefined)
+            Object.assign(body, assignment(kind, await this.#person(project, input.assignedTo)));
+        const tags = tagList(input.tags ?? []);
+        if (tags.length > 0)
+            body['tags'] = tags;
+        if (input.dueDate !== undefined)
+            body['due_date'] = input.dueDate;
+        if (input.sprint !== undefined)
+            body['milestone'] = (await this.#sprintFor(project, input.sprint)).id;
+        if (input.story !== undefined) {
+            const storyId = await this.#idOf(project, input.story, 'story', 'Pass the number of a user story as `story`.');
+            body['user_story'] = storyId;
+            // A task lives on the taskboard of its story's sprint, unless told otherwise.
+            if (input.sprint === undefined) {
+                body['milestone'] =
+                    (await this.#http.get(`${API.story.list}/${storyId}`)).milestone ?? null;
+            }
+        }
+        if (kind === 'issue') {
+            if (input.type !== undefined)
+                body['type'] = find(project, project.issueTypes, input.type, 'issue type');
+            if (input.severity !== undefined)
+                body['severity'] = find(project, project.severities, input.severity, 'severity');
+            if (input.priority !== undefined)
+                body['priority'] = find(project, project.priorities, input.priority, 'priority');
+        }
+        const epicId = input.epic === undefined
+            ? undefined
+            : await this.#idOf(project, input.epic, 'epic', 'Call list_epics for the epic numbers.');
+        const created = await this.#http.write('POST', API[kind].list, body);
+        const facts = factsOfNew(kind, project, created);
+        if (epicId !== undefined) {
+            try {
+                await this.#http.write('POST', `/epics/${epicId}/related_userstories`, {
+                    epic: epicId,
+                    user_story: created.id,
+                });
+                facts.push(['Epic', `#${input.epic}`]);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new TaigaError(`User story #${created.ref} was created, but adding it to epic #${input.epic} failed (${reason}). ` +
+                    'Do not create the story again: tell the user, who can add it to the epic in Taiga.');
+            }
+        }
+        return { ...this.#written(project, kind, created), changed: [], facts };
+    }
+    /**
+     * Change some fields of an item. Taiga refuses the change when someone else changed the same
+     * fields after `version`; fields nobody else touched are merged.
+     */
+    async updateItem(slug, ref, change) {
+        const { project, kind, id, current } = await this.#current(slug, ref);
+        const label = API[kind].label;
+        const body = {};
+        const changed = [];
+        const set = (field, value, name, before, after) => {
+            if (before === after)
+                return;
+            body[field] = value;
+            changed.push([name, before, after]);
+        };
+        const notFor = (given, kinds, why) => {
+            if (given !== undefined && kinds.includes(kind))
+                throw new TaigaError(`#${ref} is ${article(label)}: ${why}`);
+        };
+        notFor(change.sprint, ['epic'], 'epics are not planned in sprints.');
+        notFor(change.dueDate, ['epic'], 'Taiga keeps no due date for epics.');
+        for (const field of ['type', 'severity', 'priority']) {
+            notFor(change[field], ['story', 'task', 'epic'], `only issues have a ${field}.`);
+        }
+        if (change.subject !== undefined) {
+            const subject = change.subject.trim();
+            if (subject === '')
+                throw new TaigaError('The title cannot be empty.');
+            set('subject', subject, 'Title', current.subject, subject);
+        }
+        if (change.description !== undefined) {
+            const before = current.description ?? '';
+            if (before.trim() !== change.description.trim()) {
+                body['description'] = change.description;
+                changed.push(['Description', characters(before), characters(change.description)]);
+            }
+        }
+        if (change.status !== undefined) {
+            const statusId = find(project, project.statuses[kind], change.status, `${label} status`);
+            const after = nameOf(project.statuses[kind], statusId) ?? change.status;
+            set('status', statusId, 'Status', current.status_extra_info?.name ?? 'Unknown', after);
+        }
+        if (change.assignedTo !== undefined) {
+            const who = await this.#person(project, change.assignedTo);
+            const before = current.assigned_to_extra_info?.full_name_display ?? 'nobody';
+            if (before !== who.name) {
+                Object.assign(body, assignment(kind, who));
+                changed.push(['Assigned to', before, who.name]);
+            }
+        }
+        if (change.sprint !== undefined) {
+            const sprint = await this.#sprintFor(project, change.sprint);
+            const before = nameOf(project.sprints, current.milestone) ??
+                (current.milestone ? 'another sprint' : 'none (backlog)');
+            set('milestone', sprint.id, 'Sprint', before, sprint.name);
+        }
+        if (change.addTags !== undefined || change.removeTags !== undefined) {
+            const before = (current.tags ?? []).map(tagName);
+            const removed = new Set(tagList(change.removeTags ?? []));
+            const after = tagList([
+                ...before.filter((tag) => !removed.has(tag.toLowerCase())),
+                ...(change.addTags ?? []),
+            ]);
+            const show = (tags) => tags.join(', ') || 'none';
+            set('tags', after, 'Tags', show(before), show(after));
+        }
+        if (change.dueDate !== undefined) {
+            set('due_date', change.dueDate, 'Due', day(current.due_date ?? undefined) ?? 'none', change.dueDate ?? 'none');
+        }
+        if (change.blocked !== undefined) {
+            const yesNo = (value) => (value ? 'yes' : 'no');
+            set('is_blocked', change.blocked, 'Blocked', yesNo(current.is_blocked ?? false), yesNo(change.blocked));
+        }
+        if (change.blockedNote !== undefined || change.blocked === false) {
+            const note = change.blocked === false ? '' : (change.blockedNote ?? '').trim();
+            set('blocked_note', note, 'Reason blocked', current.blocked_note?.trim() || 'none', note || 'none');
+        }
+        if (kind === 'issue') {
+            const names = issueNames(project, current);
+            if (change.type !== undefined) {
+                const typeId = find(project, project.issueTypes, change.type, 'issue type');
+                set('type', typeId, 'Type', names.type ?? 'none', nameOf(project.issueTypes, typeId) ?? change.type);
+            }
+            if (change.severity !== undefined) {
+                const severityId = find(project, project.severities, change.severity, 'severity');
+                set('severity', severityId, 'Severity', names.severity ?? 'none', nameOf(project.severities, severityId) ?? change.severity);
+            }
+            if (change.priority !== undefined) {
+                const priorityId = find(project, project.priorities, change.priority, 'priority');
+                set('priority', priorityId, 'Priority', names.priority ?? 'none', nameOf(project.priorities, priorityId) ?? change.priority);
+            }
+        }
+        if (changed.length === 0) {
+            return { ...this.#written(project, kind, current), changed: [], facts: [] };
+        }
+        const version = change.version ?? current.version;
+        // Taiga answers a version from the future with the same field name as a conflict: tell them apart here.
+        if (change.version !== undefined && current.version !== undefined && change.version > current.version) {
+            throw new TaigaError(`#${ref} has no version ${change.version}: it is at version ${current.version}. Pass the version ` +
+                'get_item showed, or leave `version` out.');
+        }
+        let updated;
+        try {
+            updated = await this.#http.write('PATCH', `${API[kind].list}/${id}`, { ...body, version });
+        }
+        catch (error) {
+            if (error instanceof TaigaError && error.status === 400 && /version/i.test(error.message)) {
+                throw new TaigaError(`Not changed: someone changed the same fields of #${ref} after version ${version} was read ` +
+                    `(it is now at version ${current.version ?? 'unknown'}). Read it again with get_item, check with ` +
+                    'the user that the change still makes sense, and retry with the new version.', 409);
+            }
+            throw error;
+        }
+        return { ...this.#written(project, kind, updated), changed, facts: [] };
+    }
+    /** The item behind a reference number, read in full just now. */
+    async #current(slug, ref) {
+        const project = await this.#project(slug);
+        const { kind, id } = await this.#resolve(project, ref);
+        if (kind === undefined || id === undefined) {
+            throw new TaigaError(`Project "${project.name}" has no item #${ref}. Use a list tool to find the reference number.`, 404);
+        }
+        const current = await this.#http.get(`${API[kind].list}/${id}`);
+        return { project, kind, id, current };
+    }
+    #written(project, kind, item) {
+        return {
+            kind,
+            ref: item.ref,
+            subject: item.subject,
+            project: project.name,
+            url: webAddress(this.#baseUrl, project.slug, kind, item.ref),
+            version: item.version,
+        };
+    }
+    /** Who `assigned_to` points at in a change: a member, the signed-in user, or nobody. */
+    async #person(project, wanted) {
+        const key = fold(wanted);
+        if (UNASSIGNED.has(key))
+            return { id: null, name: 'nobody' };
+        if (ME.has(key)) {
+            const me = await this.currentUser();
+            const member = project.members.find((m) => m.id === me.id);
+            if (member === undefined) {
+                throw new TaigaError(`The signed-in user is not a member of project "${project.name}", so cannot be assigned.`);
+            }
+            return { id: member.id, name: member.name };
+        }
+        const member = findMember(project, wanted);
+        return { id: member.id, name: member.name };
+    }
+    /** The sprint a change puts an item in: one by name, the running one, or none (the backlog). */
+    async #sprintFor(project, wanted) {
+        // A sprint that really is named "Backlog" or "Current" wins over the keyword.
+        const named = project.sprints.find((sprint) => same(sprint.name, wanted) || same(sprint.slug, wanted));
+        if (named !== undefined)
+            return { id: named.id, name: named.name };
+        if (same(wanted, 'backlog') || same(wanted, 'none'))
+            return { id: null, name: 'none (backlog)' };
+        if (same(wanted, 'current')) {
+            const running = await this.#currentSprint(project);
+            return { id: running.id, name: running.name };
+        }
+        const open = project.sprints.filter((sprint) => !sprint.closed).map((sprint) => `"${sprint.name}"`);
+        throw new TaigaError(`Project "${project.name}" has no sprint "${wanted}". Open sprints: ${open.join(', ') || 'none'}. ` +
+            'Or pass "current" for the running sprint, or "backlog" for none.');
+    }
+    #project(slug) {
+        const key = slug.trim().toLowerCase();
+        const cached = this.#projects.get(key);
+        const now = this.#now().getTime();
+        if (cached !== undefined && now - cached.at < PROJECT_CACHE_MS)
+            return cached.project;
+        const project = this.#http
+            .get('/projects/by_slug', { slug: key })
+            .then(toProject, (error) => {
+            this.#projects.delete(key);
+            if (error instanceof TaigaError && error.status === 404) {
+                throw new TaigaError(`No project with slug "${slug}" that the signed-in user can read. Call list_projects to see the valid slugs.`, 404);
+            }
+            throw error;
+        });
+        this.#projects.set(key, { at: now, project });
+        return project;
+    }
+    /* ------------------------------- filters ------------------------------- */
+    /** The filters every kind of item has, as Taiga's query, and whose items they select in words. */
+    async #commonFilters(project, kind, filters) {
+        const who = await this.#assignee(project, filters);
+        const finished = API[kind].finished;
+        if (finished === undefined && (filters.finishedFrom ?? filters.finishedTo) !== undefined) {
+            throw new TaigaError(`Taiga keeps no finish date for ${API[kind].label}s. Filter them with \`closed\`.`);
+        }
+        return {
+            assignee: who?.label,
+            query: {
+                project: project.id,
+                status: optional(filters.status, (name) => find(project, project.statuses[kind], name, `${API[kind].label} status`)),
+                status__is_closed: filters.closed,
+                assigned_to: who?.value,
+                q: searchWords(filters.search),
+                tags: filters.tag?.trim().toLowerCase() || undefined,
+                created_date__gte: filters.createdFrom,
+                created_date__lte: optional(filters.createdTo, endOfDay),
+                ...(finished === undefined
+                    ? {}
+                    : {
+                        [`${finished}__gte`]: filters.finishedFrom,
+                        [`${finished}__lte`]: optional(filters.finishedTo, endOfDay),
+                    }),
+            },
+        };
+    }
+    async #assignee(project, filters) {
+        if (filters.assignedTo === undefined) {
+            return filters.assignedToMe ? { value: (await this.currentUser()).id, label: 'me' } : undefined;
+        }
+        if (filters.assignedToMe) {
+            throw new TaigaError('Pass either `assigned_to_me` or `assigned_to`, not both.');
+        }
+        if (UNASSIGNED.has(fold(filters.assignedTo)))
+            return { value: 'null', label: 'nobody' };
+        const member = findMember(project, filters.assignedTo);
+        return { value: member.id, label: member.name };
+    }
+    /** Which kind of item a reference number belongs to, and its id. Both missing: no such item. */
+    async #resolve(project, ref) {
+        const resolved = await this.#http.get('/resolver', { project: project.slug, ref });
+        const kind = KINDS.find((candidate) => resolved[API[candidate].resolved] !== undefined);
+        return kind === undefined ? {} : { kind, id: resolved[API[kind].resolved] };
+    }
+    /** The id behind a reference number that must be of one kind, e.g. the epic to filter stories by. */
+    async #idOf(project, ref, wanted, hint) {
+        const { kind, id } = await this.#resolve(project, ref);
+        if (kind === wanted && id !== undefined)
+            return id;
+        const label = API[wanted].label;
+        throw new TaigaError(kind === undefined
+            ? `Project "${project.name}" has no ${label} #${ref}. ${hint}`
+            : `#${ref} in project "${project.name}" is ${article(API[kind].label)}, not ${article(label)}. ${hint}`, 404);
+    }
+    /** Turn what the user called a sprint into Taiga's filter, and into words for the answer. */
+    async #sprintFilter(project, wanted, 
+    /** Stories can be in no sprint (the backlog); Taiga cannot list tasks that way. */
+    of) {
+        // A sprint that really is named "Backlog" or "Current" wins over the keyword.
+        const named = project.sprints.find((sprint) => same(sprint.name, wanted) || same(sprint.slug, wanted));
+        if (named !== undefined)
+            return { query: { milestone: named.id }, label: `sprint "${named.name}"` };
+        if (same(wanted, 'backlog')) {
+            if (of === 'story')
+                return { query: { milestone__isnull: true }, label: 'backlog (no sprint)' };
+            throw new TaigaError('Tasks cannot be listed by backlog. List the backlog stories with list_user_stories (sprint: "backlog"), then the tasks of one story with `story`.');
+        }
+        if (!same(wanted, 'current')) {
+            throw new TaigaError(`Project "${project.name}" has no sprint "${wanted}". Pass a sprint name from list_sprints` +
+                (of === 'story' ? ', "current" or "backlog".' : ' or "current".'));
+        }
+        const running = await this.#currentSprint(project);
+        return { query: { milestone: running.id }, label: `current sprint "${running.name}"` };
+    }
+    /** The open sprint whose dates include today, or an error that lists the open ones. */
+    async #currentSprint(project) {
+        const open = await this.#http.get('/milestones', { project: project.id, closed: false }, { everything: true });
+        const today = localDay(this.#now());
+        // Newest first, so with overlapping sprints the one that started last is taken.
+        const running = open.find((sprint) => isRunning(sprint, today));
+        if (running === undefined) {
+            const others = open.map((s) => `"${s.name}" (${s.estimated_start} to ${s.estimated_finish})`);
+            throw new TaigaError(`No sprint of project "${project.name}" is running today (${today}). ` +
+                (others.length > 0
+                    ? `Open sprints: ${others.join(', ')}. Pass one of these names as \`sprint\`.`
+                    : 'It has no open sprint. Call list_sprints with closed: true to see past ones.'));
+        }
+        return running;
+    }
+}
+/* -------------------------- raw → trimmed shapes -------------------------- */
+/** The id behind a name the user said, or an error that lists the names that exist. */
+function find(project, options, wanted, what) {
+    const match = options.find((option) => same(option.name, wanted));
+    if (match !== undefined)
+        return match.id;
+    throw new TaigaError(`Project "${project.name}" has no ${what} "${wanted}". It has: ${options.map((o) => o.name).join(', ') || 'none'}.`);
+}
+/** The one member a name, part of a name, or a username points at; or an error that says who there is. */
+function findMember(project, wanted) {
+    const key = fold(wanted);
+    const show = (member) => `${member.name} (${member.username})`;
+    const exact = project.members.filter((m) => fold(m.name) === key || fold(m.username) === key);
+    const matches = exact.length > 0
+        ? exact
+        : project.members.filter((m) => fold(m.name).includes(key) || fold(m.username).includes(key));
+    const [only, ...others] = matches;
+    if (only !== undefined && others.length === 0)
+        return only;
+    if (only === undefined) {
+        const listed = project.members.slice(0, MEMBERS_LISTED).map(show).join(', ');
+        const more = project.members.length - MEMBERS_LISTED;
+        throw new TaigaError(`Project "${project.name}" has no member "${wanted}". Members: ${listed || 'none'}${more > 0 ? `, and ${more} more` : ''}.`);
+    }
+    throw new TaigaError(`"${wanted}" matches several members of project "${project.name}": ${matches.map(show).join(', ')}. Pass the full name or the username.`);
+}
+/** What Taiga's `q` filter gets: the words, or nothing when there are none. */
+const searchWords = (search) => search?.trim() || undefined;
+/** The last moment of a day, so that "to 2026-03-31" includes what happened on the 31st. */
+const endOfDay = (date) => `${date}T23:59:59Z`;
+/** A week without a single event in a project people work in is worth pointing out. */
+const LOG_SILENT_DAYS = 7;
+/** The day the activity log ends, when the question reaches past it or the log has gone quiet. */
+function logEnd(newest, from, now) {
+    if (newest === undefined)
+        return undefined;
+    const quiet = now.getTime() - Date.parse(newest) > LOG_SILENT_DAYS * 86_400_000;
+    const askedPast = from !== undefined && newest.slice(0, 10) < from;
+    return quiet || askedPast ? day(newest) : undefined;
+}
+const authorOf = (entry) => entry.user?.name || entry.user?.username || 'Unknown';
+/** A value of a history entry, short enough for one line. */
+function shown(value) {
+    if (value === null || value === undefined || value === '' || value === 'None')
+        return 'none';
+    if (Array.isArray(value) && value.every((v) => typeof v !== 'object' || v === null)) {
+        return value.length === 0 ? 'none' : value.map(String).join(', ');
+    }
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    const line = text.replace(/\s+/g, ' ').trim();
+    return line.length > 80 ? `${line.slice(0, 80)}…` : line;
+}
+/** What one history entry changed, in words: `status: New → In progress; assigned to: none → Linh Tran`. */
+function describeChange(diff) {
+    const label = (key) => (key === 'milestone' ? 'sprint' : key.replaceAll('_', ' '));
+    const parts = [];
+    for (const [key, value] of Object.entries(diff)) {
+        // Board positions say nothing, and an `_html` field repeats the change of the field it renders.
+        if (SILENT_CHANGES.has(key) || key.endsWith('_order') || key.endsWith('_html'))
+            continue;
+        if (key.endsWith('_diff')) {
+            parts.push(`${label(key.slice(0, -'_diff'.length))} edited`);
+        }
+        else if (Array.isArray(value) && value.length === 2) {
+            parts.push(`${label(key)}: ${shown(value[0])} → ${shown(value[1])}`);
+        }
+        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // Points are kept per role: { "Back": ["?", "3"] }. Attachments: { new: [...], deleted: [...] }.
+            const inner = Object.entries(value).flatMap(([name, pair]) => Array.isArray(pair) && pair.length === 2 && !Array.isArray(pair[0]) && typeof pair[0] !== 'object'
+                ? [`${label(key)} (${name}): ${shown(pair[0])} → ${shown(pair[1])}`]
+                : []);
+            parts.push(...(inner.length > 0 ? inner : [`${label(key)} changed`]));
+        }
+        else {
+            parts.push(`${label(key)} changed`);
+        }
+    }
+    return parts.length === 0 ? undefined : parts.join('; ');
+}
+const capital = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+const round = (n) => Math.round(n * 10) / 10;
+const MODELS = {
+    userstory: { kind: 'story', label: 'story' },
+    task: { kind: 'task', label: 'task' },
+    issue: { kind: 'issue', label: 'issue' },
+    epic: { kind: 'epic', label: 'epic' },
+    relateduserstory: { kind: 'epic', label: 'story' },
+    wikipage: { kind: 'wiki', label: 'wiki page' },
+    milestone: { kind: 'sprint', label: 'sprint' },
+};
+const isRef = (value) => typeof value === 'object' && value !== null;
+/** "story #42 Retry failed card payments", "wiki page release-steps", "sprint "Sprint 7"". */
+function itemName(label, object) {
+    if (object === undefined)
+        return label;
+    if (object.ref !== undefined)
+        return `${label} #${object.ref}${object.subject ? ` ${oneLine(object.subject)}` : ''}`;
+    if (object.slug !== undefined && label === 'wiki page')
+        return `${label} ${object.slug}`;
+    if (object.name !== undefined)
+        return `${label} "${object.name}"`;
+    return label;
+}
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+const COMMENT_IN_ACTIVITY = 300;
+/** One timeline event in words, or nothing when it does not match or only reorders a board. */
+function describeEvent(event, filters) {
+    const [, model = '', action = ''] = event.event_type.split('.');
+    const known = MODELS[model];
+    const data = event.data ?? {};
+    if (filters.kind !== undefined && known?.kind !== filters.kind)
+        return undefined;
+    const comment = data.comment?.trim();
+    if (filters.commentsOnly && !comment)
+        return undefined;
+    const own = isRef(data[model]) ? data[model] : undefined;
+    let subject;
+    let verb;
+    if (model === 'relateduserstory') {
+        const story = isRef(data['userstory']) ? data['userstory'] : undefined;
+        const epic = isRef(data['epic']) ? data['epic'] : undefined;
+        subject = `${itemName('story', { ref: story?.ref, subject: own?.subject ?? story?.subject })} ${action === 'delete' ? 'from' : 'to'} ${itemName('epic', epic === undefined ? undefined : { ref: epic.ref })}`;
+        verb = action === 'create' ? 'linked' : action === 'delete' ? 'unlinked' : 'changed the link of';
+    }
+    else {
+        subject = itemName(known?.label ?? model, own);
+        verb =
+            action === 'create'
+                ? 'created'
+                : action === 'delete'
+                    ? 'deleted'
+                    : comment
+                        ? 'commented on'
+                        : 'changed';
+    }
+    const refs = [own?.ref, isRef(data['userstory']) ? data['userstory'].ref : undefined];
+    if (filters.ref !== undefined && !refs.includes(filters.ref))
+        return undefined;
+    const changes = describeChange(data.values_diff ?? {});
+    // Moving cards around a board is recorded too; it says nothing.
+    if (action === 'change' && !comment && changes === undefined)
+        return undefined;
+    const parts = [
+        `${verb} ${subject}`,
+        changes,
+        comment && `"${truncateText(oneLine(comment), COMMENT_IN_ACTIVITY)}"`,
+    ];
+    return {
+        at: event.created.slice(0, 16).replace('T', ' '),
+        author: data.user?.name || data.user?.username || 'Unknown',
+        what: parts.filter(Boolean).join(' · '),
+    };
+}
+const truncateText = (text, max) => text.length <= max ? text : `${text.slice(0, max).trimEnd()}…`;
+function toTask(project, task) {
+    return {
+        ...toSummary(task),
+        story: task.user_story_extra_info?.ref,
+        sprint: nameOf(project.sprints, task.milestone),
+        finished: day(task.finished_date ?? undefined),
+    };
+}
+function toWikiSummary(page, links) {
+    return {
+        slug: page.slug,
+        title: links.find((link) => link.href === page.slug)?.title,
+        modified: day(page.modified_date),
+        edits: page.editions ?? 0,
+        length: page.content?.length ?? 0,
+    };
+}
+const nameOf = (options, id) => options.find((option) => option.id === id)?.name;
+const named = (list) => (list ?? []).map(({ id, name }) => ({ id, name }));
+/** Statuses also say whether they count as done. */
+const statuses = (list) => (list ?? []).map(({ id, name, is_closed }) => ({ id, name, closed: is_closed ?? false }));
+function toProject(raw) {
+    return {
+        id: raw.id,
+        name: raw.name,
+        slug: raw.slug,
+        statuses: {
+            story: statuses(raw.us_statuses),
+            issue: statuses(raw.issue_statuses),
+            epic: statuses(raw.epic_statuses),
+            task: statuses(raw.task_statuses),
+        },
+        customFields: {
+            story: named(raw.userstory_custom_attributes),
+            issue: named(raw.issue_custom_attributes),
+            epic: named(raw.epic_custom_attributes),
+            task: named(raw.task_custom_attributes),
+        },
+        severities: named(raw.severities),
+        priorities: named(raw.priorities),
+        issueTypes: named(raw.issue_types),
+        sprints: (raw.milestones ?? []).map(({ id, name, slug, closed }) => ({ id, name, slug, closed })),
+        members: (raw.members ?? []).map((member) => ({
+            id: member.id,
+            username: member.username,
+            name: member.full_name_display || member.full_name || member.username,
+            role: member.role_name || undefined,
+        })),
+        description: raw.description?.trim() ?? '',
+        isPrivate: raw.is_private ?? false,
+        tags: Object.keys(raw.tags_colors ?? {}).sort((a, b) => a.localeCompare(b)),
+        modules: [
+            ['backlog', raw.is_backlog_activated],
+            ['kanban', raw.is_kanban_activated],
+            ['issues', raw.is_issues_activated],
+            ['epics', raw.is_epics_activated],
+            ['wiki', raw.is_wiki_activated],
+        ].flatMap(([name, on]) => (on ? [name] : [])),
+    };
+}
+const isRunning = (sprint, today) => !sprint.closed && sprint.estimated_start <= today && today <= sprint.estimated_finish;
+function toSprint(sprint, today) {
+    return {
+        name: sprint.name,
+        start: sprint.estimated_start,
+        finish: sprint.estimated_finish,
+        closed: sprint.closed,
+        current: isRunning(sprint, today),
+        totalPoints: sprint.total_points ?? 0,
+        closedPoints: sprint.closed_points ?? 0,
+        stories: sprint.user_stories?.length ?? 0,
+        // By status, like the `closed` filter of the list tools. A story's own `is_closed` flag also
+        // turns on when all its tasks are closed, which would disagree with the status shown.
+        storiesDone: sprint.user_stories?.filter((story) => story.status_extra_info?.is_closed).length ?? 0,
+    };
+}
+function toSummary(item) {
+    return {
+        ref: item.ref,
+        subject: item.subject,
+        status: item.status_extra_info?.name ?? 'Unknown',
+        closed: item.status_extra_info?.is_closed ?? false,
+        assignee: item.assigned_to_extra_info?.full_name_display,
+        blocked: item.is_blocked ?? false,
+    };
+}
+function issueNames(project, issue) {
+    return {
+        type: nameOf(project.issueTypes, issue.type),
+        severity: nameOf(project.severities, issue.severity),
+        priority: nameOf(project.priorities, issue.priority),
+    };
+}
+const tagName = (tag) => (typeof tag === 'string' ? tag : tag[0]);
+/** Taiga's web app keeps its items at these paths. */
+const WEB_PATH = {
+    story: 'us',
+    task: 'task',
+    issue: 'issue',
+    epic: 'epic',
+};
+/**
+ * The item in Taiga's web app. A self-hosted Taiga serves the app and the API from one address;
+ * Taiga cloud serves its API from another host.
+ */
+function webAddress(apiBase, slug, kind, ref) {
+    try {
+        const url = new URL(apiBase);
+        if (url.hostname === 'api.taiga.io')
+            url.hostname = 'tree.taiga.io';
+        return `${url.origin}${url.pathname.replace(/\/+$/, '')}/project/${encodeURIComponent(slug)}/${WEB_PATH[kind]}/${ref}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The fields that set who an item is assigned to. A story also keeps a list of assignees. */
+function assignment(kind, who) {
+    return kind === 'story'
+        ? { assigned_to: who.id, assigned_users: who.id === null ? [] : [who.id] }
+        : { assigned_to: who.id };
+}
+/** Tags as Taiga stores them: trimmed, lower case, each once. */
+function tagList(tags) {
+    return [...new Set(tags.map((tag) => tag.trim().toLowerCase()).filter(Boolean))];
+}
+/** A description in a line of the answer: how long it is, not what it says. */
+const characters = (text) => (text.trim() === '' ? '(empty)' : `(${text.trim().length} characters)`);
+/** What the answer says about a new item: where Taiga put it and with what. */
+function factsOfNew(kind, project, item) {
+    const facts = [
+        ['Status', item.status_extra_info?.name],
+        ['Assigned to', item.assigned_to_extra_info?.full_name_display ?? 'nobody'],
+        [
+            'User story',
+            item.user_story_extra_info
+                ? `#${item.user_story_extra_info.ref} ${item.user_story_extra_info.subject}`
+                : undefined,
+        ],
+        ['Sprint', nameOf(project.sprints, item.milestone) ?? (kind === 'issue' ? undefined : 'none (backlog)')],
+        ['Tags', (item.tags ?? []).map(tagName).join(', ') || undefined],
+        ['Due', day(item.due_date ?? undefined)],
+    ];
+    if (kind === 'issue') {
+        const names = issueNames(project, item);
+        facts.push(['Type', names.type], ['Severity', names.severity], ['Priority', names.priority]);
+    }
+    return facts.filter((fact) => fact[1] !== undefined);
+}
+/** The facts that only one kind of item has, as label and value. Missing ones are left out. */
+function factsOf(kind, project, item) {
+    const facts = [
+        ['Due', day(item.due_date ?? undefined)],
+        ['Finished', day((kind === 'story' ? item.finish_date : item.finished_date) ?? undefined)],
+    ];
+    if (kind === 'story') {
+        facts.push(['Sprint', item.milestone_name ?? 'none (backlog)'], ['Points', item.total_points == null ? undefined : String(item.total_points)], ['Epics', item.epics?.map((epic) => `#${epic.ref} ${epic.subject}`).join('; ') || undefined]);
+    }
+    else if (kind === 'issue') {
+        const names = issueNames(project, item);
+        facts.push(['Type', names.type], ['Severity', names.severity], ['Priority', names.priority]);
+    }
+    else if (kind === 'task') {
+        const story = item.user_story_extra_info;
+        facts.push(['User story', story ? `#${story.ref} ${story.subject}` : 'none'], ['Sprint', nameOf(project.sprints, item.milestone)]);
+    }
+    else {
+        const counts = item.user_stories_counts;
+        facts.push(['Stories', counts ? progress(counts.progress, counts.total) : undefined]);
+    }
+    const watchers = (item.watchers ?? []).map((id) => project.members.find((member) => member.id === id)?.name ?? 'a former member');
+    facts.push(['Watchers', watchers.join(', ') || undefined], ['Votes', item.total_voters ? String(item.total_voters) : undefined]);
+    return facts.filter((fact) => fact[1] !== undefined);
+}
+//# sourceMappingURL=client.js.map