@stubbedev/atlassian-mcp 0.4.5 → 0.5.1

package/dist/jira.js

@@ -1,979 +0,0 @@
-import { execSync } from 'child_process';
-import { createWriteStream } from 'fs';
-import { Readable } from 'stream';
-import { pipeline } from 'stream/promises';
-import { resolve as resolvePath } from 'path';
-import { buildAttachmentResult, formatBytes } from './attachment.js';
-import { MAX_VIDEO_SOURCE_BYTES } from './video.js';
-const JIRA_KEY_IN_BRANCH_RE = /\b([A-Z][A-Z0-9]+)-\d+\b/;
-const EMOJI_RE = /\p{Extended_Pictographic}/u;
-function text(t) {
-    return { content: [{ type: 'text', text: t }] };
-}
-// Cap long free-text (e.g. issue descriptions) so a single verbose ticket does
-// not flood the model's context. Returns the text untouched when within cap.
-function capText(value, max) {
-    if (max <= 0 || value.length <= max)
-        return value;
-    const more = value.length - max;
-    return `${value.slice(0, max)}\n... (truncated, ${more} more chars — pass fullDescription=true for the rest)`;
-}
-function pagination(total, startAt, count) {
-    const end = startAt + count;
-    return total > end ? ` (showing ${startAt + 1}–${end} of ${total}, use startAt=${end} for next page)` : '';
-}
-function buildJQL(args) {
-    if (args.jql) {
-        if (args.jql.length > 2000)
-            throw new Error('JQL query too long (max 2000 characters).');
-        return args.jql;
-    }
-    const clauses = [];
-    if (args.query)
-        clauses.push(`text ~ ${JSON.stringify(args.query)}`);
-    if (args.project)
-        clauses.push(`project = "${args.project}"`);
-    if (args.status)
-        clauses.push(`status = "${args.status}"`);
-    if (args.assignee)
-        clauses.push(`assignee = "${args.assignee}"`);
-    if (args.issueType)
-        clauses.push(`issuetype = "${args.issueType}"`);
-    if (clauses.length === 0)
-        throw new Error('Provide at least one of: query, jql, project, status, assignee, issueType');
-    return clauses.join(' AND ') + ' ORDER BY updated DESC';
-}
-function safeExec(cmd) {
-    try {
-        return execSync(cmd, { encoding: 'utf-8' }).trim();
-    }
-    catch {
-        return '';
-    }
-}
-function parseJiraErrorDetails(errText) {
-    const trimmed = errText.trim();
-    if (!trimmed)
-        return '';
-    try {
-        const parsed = JSON.parse(trimmed);
-        const parts = [];
-        if (Array.isArray(parsed.errorMessages)) {
-            for (const msg of parsed.errorMessages) {
-                const clean = (msg ?? '').trim();
-                if (clean)
-                    parts.push(clean);
-            }
-        }
-        if (parsed.errors && typeof parsed.errors === 'object') {
-            for (const [field, msg] of Object.entries(parsed.errors)) {
-                const clean = (msg ?? '').trim();
-                if (clean)
-                    parts.push(`${field}: ${clean}`);
-            }
-        }
-        if (parts.length > 0)
-            return parts.join(' | ');
-    }
-    catch {
-        // Fallback to raw text below
-    }
-    return trimmed.length > 500 ? `${trimmed.slice(0, 500)}...` : trimmed;
-}
-function formatJiraError(status, method, path, details) {
-    const prefix = `Jira ${status} ${method} ${path}`;
-    if (status === 400)
-        return `${prefix}. Invalid request or parameters. ${details}`.trim();
-    if (status === 401)
-        return `${prefix}. Authentication failed. Check JIRA_ACCESS_TOKEN.`;
-    if (status === 403)
-        return `${prefix}. Permission denied. Check Jira permissions for this token.`;
-    if (status === 404)
-        return `${prefix}. Resource not found. Verify issue/project identifiers and access.`;
-    if (status === 409)
-        return `${prefix}. Conflict. Refresh and retry. ${details}`.trim();
-    return details ? `${prefix}. ${details}` : prefix;
-}
-function validateCommentBody(body) {
-    const trimmed = body.trim();
-    if (!trimmed) {
-        throw new Error('Jira comment body must not be empty.');
-    }
-    if (EMOJI_RE.test(trimmed)) {
-        throw new Error('Jira comments must not include emoji. Use concise Jira wiki markup or plain text only.');
-    }
-    return trimmed;
-}
-export class JiraClient {
-    baseUrl;
-    headers;
-    currentUserCache;
-    projectsCache;
-    issueLinkingEnabled;
-    epicLinkFieldIdCache;
-    issueTypeCache = new Map();
-    constructor(baseUrl, token) {
-        this.baseUrl = baseUrl.replace(/\/$/, '');
-        this.headers = {
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
-            Accept: 'application/json',
-        };
-    }
-    issueUrl(issueKey) {
-        return `${this.baseUrl}/browse/${encodeURIComponent(issueKey)}`;
-    }
-    projectUrl(projectKey) {
-        return `${this.baseUrl}/projects/${encodeURIComponent(projectKey)}`;
-    }
-    boardUrl(boardId) {
-        return `${this.baseUrl}/secure/RapidBoard.jspa?rapidView=${boardId}`;
-    }
-    sprintUrl(boardId, sprintId) {
-        return `${this.boardUrl(boardId)}&sprint=${sprintId}`;
-    }
-    async requestWithBase(apiBase, method, path, body) {
-        const url = `${this.baseUrl}${apiBase}${path}`;
-        const opts = { method, headers: this.headers, signal: AbortSignal.timeout(30_000) };
-        if (body !== undefined)
-            opts.body = JSON.stringify(body);
-        const res = await fetch(url, opts);
-        if (!res.ok) {
-            const errText = await res.text();
-            const details = parseJiraErrorDetails(errText);
-            throw new Error(formatJiraError(res.status, method, path, details));
-        }
-        if (res.status === 204)
-            return null;
-        const raw = await res.text();
-        if (!raw)
-            return null;
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    async request(method, path, body) {
-        return this.requestWithBase('/rest/api/2', method, path, body);
-    }
-    async requestAgile(method, path, body) {
-        return this.requestWithBase('/rest/agile/1.0', method, path, body);
-    }
-    normalizeIdentity(value) {
-        return (value ?? '').trim().toLowerCase();
-    }
-    async getCurrentUser() {
-        if (this.currentUserCache)
-            return this.currentUserCache;
-        const me = await this.request('GET', '/myself');
-        if (!me) {
-            throw new Error('Could not determine current Jira user identity.');
-        }
-        this.currentUserCache = me;
-        return me;
-    }
-    async whoami() {
-        return this.getCurrentUser();
-    }
-    async getIssueLinkingEnabled() {
-        if (this.issueLinkingEnabled !== undefined)
-            return this.issueLinkingEnabled;
-        const config = await this.request('GET', '/configuration');
-        this.issueLinkingEnabled = config?.issueLinkingEnabled ?? false;
-        return this.issueLinkingEnabled;
-    }
-    async getEpicLinkFieldId() {
-        if (this.epicLinkFieldIdCache !== undefined)
-            return this.epicLinkFieldIdCache;
-        const fields = (await this.request('GET', '/field')) ?? [];
-        const match = fields.find((f) => f.schema?.custom === 'com.pyxis.greenhopper.jira:gh-epic-link');
-        this.epicLinkFieldIdCache = match?.id ?? null;
-        return this.epicLinkFieldIdCache;
-    }
-    async getIssueType(issueKey) {
-        const cached = this.issueTypeCache.get(issueKey);
-        if (cached)
-            return cached;
-        const data = await this.request('GET', `/issue/${encodeURIComponent(issueKey)}?fields=issuetype`);
-        const name = data?.fields?.issuetype?.name ?? null;
-        if (name)
-            this.issueTypeCache.set(issueKey, name);
-        return name;
-    }
-    async assertOwnComment(comment) {
-        const me = await this.getCurrentUser();
-        const commentAuthorName = this.normalizeIdentity(comment.author.name);
-        const commentAuthorKey = this.normalizeIdentity(comment.author.key);
-        const commentAuthorDisplayName = this.normalizeIdentity(comment.author.displayName);
-        const meName = this.normalizeIdentity(me.name);
-        const meKey = this.normalizeIdentity(me.key);
-        const meDisplayName = this.normalizeIdentity(me.displayName);
-        const hasStrongCommentIdentity = commentAuthorName.length > 0 || commentAuthorKey.length > 0;
-        const hasStrongUserIdentity = meName.length > 0 || meKey.length > 0;
-        const matchesByNameOrKey = (commentAuthorName.length > 0 && (commentAuthorName === meName || commentAuthorName === meKey))
-            || (commentAuthorKey.length > 0 && (commentAuthorKey === meName || commentAuthorKey === meKey));
-        const matchesByDisplayNameFallback = !hasStrongCommentIdentity
-            && !hasStrongUserIdentity
-            && commentAuthorDisplayName.length > 0
-            && commentAuthorDisplayName === meDisplayName;
-        if (matchesByNameOrKey || matchesByDisplayNameFallback) {
-            return;
-        }
-        throw new Error(`You can only edit your own Jira comments. Comment ${comment.id} is authored by ${comment.author.displayName}.`);
-    }
-    async addIssuesToSprintInternal(sprintId, issueKeys) {
-        await this.requestAgile('POST', `/sprint/${sprintId}/issue`, { issues: issueKeys });
-    }
-    async createIssueInternal(args) {
-        const projectKey = await this.resolveProjectKey(args.projectKey);
-        const fields = {
-            project: { key: projectKey },
-            issuetype: { name: args.issueType },
-            summary: args.summary,
-        };
-        if (args.description)
-            fields.description = args.description;
-        if (args.assignee)
-            fields.assignee = { name: args.assignee };
-        if (args.priority)
-            fields.priority = { name: args.priority };
-        if (args.labels?.length)
-            fields.labels = args.labels;
-        if (args.fixVersion)
-            fields.fixVersions = [{ name: args.fixVersion }];
-        let epicLinkTarget = args.epicLink?.trim() || undefined;
-        if (args.parent) {
-            const parentType = await this.getIssueType(args.parent);
-            if (parentType === 'Epic') {
-                epicLinkTarget = epicLinkTarget ?? args.parent;
-            }
-            else {
-                fields.parent = { key: args.parent };
-            }
-        }
-        if (epicLinkTarget) {
-            const epicFieldId = await this.getEpicLinkFieldId();
-            if (!epicFieldId) {
-                throw new Error('Epic Link custom field not found on this Jira instance. Set it manually in the Jira UI.');
-            }
-            fields[epicFieldId] = epicLinkTarget;
-        }
-        return this.request('POST', '/issue', { fields });
-    }
-    async updateIssueFieldsInternal(args) {
-        const fields = {};
-        if (args.summary !== undefined)
-            fields.summary = args.summary;
-        if (args.description !== undefined)
-            fields.description = args.description;
-        if (args.assignee !== undefined)
-            fields.assignee = args.assignee ? { name: args.assignee } : null;
-        if (args.priority !== undefined)
-            fields.priority = { name: args.priority };
-        if (args.labels !== undefined)
-            fields.labels = args.labels;
-        if (args.fixVersion !== undefined)
-            fields.fixVersions = args.fixVersion ? [{ name: args.fixVersion }] : [];
-        if (args.epicLink !== undefined) {
-            const epicFieldId = await this.getEpicLinkFieldId();
-            if (!epicFieldId) {
-                throw new Error('Epic Link custom field not found on this Jira instance. Set it manually in the Jira UI.');
-            }
-            fields[epicFieldId] = args.epicLink ? args.epicLink : null;
-        }
-        if (Object.keys(fields).length === 0)
-            return false;
-        await this.request('PUT', `/issue/${encodeURIComponent(args.issueKey)}`, { fields });
-        return true;
-    }
-    async resolveTransitionId(issueKey, transitionId, transitionName) {
-        if (transitionId)
-            return transitionId;
-        const requestedName = transitionName?.trim();
-        if (!requestedName) {
-            throw new Error('Provide transitionId or transitionName');
-        }
-        const data = await this.request('GET', `/issue/${encodeURIComponent(issueKey)}/transitions`);
-        const transitions = data?.transitions ?? [];
-        const lowered = requestedName.toLowerCase();
-        const match = transitions.find((t) => t.name.toLowerCase() === lowered);
-        if (!match) {
-            const available = transitions.map((t) => t.name).join(', ') || '(none)';
-            throw new Error(`Transition "${requestedName}" not found for ${issueKey}. Available: ${available}`);
-        }
-        return match.id;
-    }
-    async transitionIssueInternal(issueKey, transitionId) {
-        await this.request('POST', `/issue/${encodeURIComponent(issueKey)}/transitions`, {
-            transition: { id: transitionId },
-        });
-    }
-    async resolveProjectKey(projectKey) {
-        if (projectKey)
-            return projectKey;
-        if (!this.projectsCache) {
-            this.projectsCache = (await this.request('GET', '/project?maxResults=100')) ?? [];
-        }
-        const projects = this.projectsCache;
-        if (projects.length === 0) {
-            throw new Error('No Jira projects found for your account.');
-        }
-        const keys = new Set(projects.map((p) => p.key));
-        const branch = safeExec('git rev-parse --abbrev-ref HEAD');
-        const branchMatch = branch.match(JIRA_KEY_IN_BRANCH_RE);
-        const branchProjectKey = branchMatch?.[1];
-        if (branchProjectKey && keys.has(branchProjectKey)) {
-            return branchProjectKey;
-        }
-        if (projects.length === 1) {
-            return projects[0].key;
-        }
-        const shown = projects.slice(0, 20);
-        const lines = shown.map((p, i) => `${i + 1}. ${p.key} — ${p.name}`);
-        const extra = projects.length > shown.length ? `\n...and ${projects.length - shown.length} more.` : '';
-        throw new Error(`Please provide projectKey (or project) for this Jira action. Choose one of these project codes:\n${lines.join('\n')}${extra}`);
-    }
-    async searchIssues(args) {
-        const { maxResults = 20, startAt = 0 } = args;
-        const jql = buildJQL(args);
-        const params = new URLSearchParams({
-            jql,
-            maxResults: String(maxResults),
-            startAt: String(startAt),
-            fields: 'summary,status,assignee,priority,issuetype',
-        });
-        const data = await this.request('GET', `/search?${params}`);
-        if (!data)
-            return text('No results.');
-        const lines = data.issues.map((i, idx) => {
-            const assignee = i.fields.assignee?.displayName ?? 'Unassigned';
-            return `${startAt + idx + 1}. [${i.key}] ${i.fields.summary} | ${i.fields.status.name} | ${assignee} | ${this.issueUrl(i.key)}`;
-        });
-        const page = pagination(data.total, startAt, data.issues.length);
-        return text(`Found ${data.total} issues${page}:\n${lines.join('\n')}`);
-    }
-    async findIssues(query, maxResults = 10) {
-        const jql = buildJQL({ query });
-        const params = new URLSearchParams({
-            jql,
-            maxResults: String(maxResults),
-            startAt: '0',
-            fields: 'summary,status,issuetype',
-        });
-        const data = await this.request('GET', `/search?${params}`);
-        return (data?.issues ?? []).map((i) => ({
-            key: i.key,
-            summary: i.fields.summary,
-            status: i.fields.status.name,
-            type: i.fields.issuetype.name,
-        }));
-    }
-    async myIssues(args) {
-        return this.searchIssues({
-            jql: 'assignee = currentUser() ORDER BY updated DESC',
-            maxResults: args.maxResults,
-            startAt: args.startAt,
-        });
-    }
-    async getProjects(args) {
-        const limit = args.maxResults ?? 50;
-        const data = await this.request('GET', `/project?maxResults=${limit}`);
-        if (!data || data.length === 0)
-            return text('No projects found.');
-        const lines = data.map((p, i) => `${i + 1}. [${p.key}] ${p.name} (${p.projectTypeKey}) | ${this.projectUrl(p.key)}`);
-        return text(`${data.length} project(s):\n${lines.join('\n')}`);
-    }
-    async getIssueTypes(args) {
-        const projectKey = await this.resolveProjectKey(args.projectKey);
-        const data = await this.request('GET', `/project/${encodeURIComponent(projectKey)}/statuses`);
-        if (!data || data.length === 0)
-            return text('No issue types found.');
-        const lines = data.map((t) => {
-            const statuses = t.statuses.map((s) => s.name).join(', ');
-            return `${t.name}: ${statuses}`;
-        });
-        return text(`Issue types and statuses for ${projectKey}:\n${lines.join('\n')}`);
-    }
-    async getSprints(args) {
-        const { boardId, maxResults = 20, startAt = 0 } = args;
-        const params = new URLSearchParams({
-            maxResults: String(maxResults),
-            startAt: String(startAt),
-        });
-        if (args.state)
-            params.set('state', args.state);
-        const data = await this.requestAgile('GET', `/board/${boardId}/sprint?${params}`);
-        if (!data || data.values.length === 0)
-            return text(`No sprints found for board ${boardId}.`);
-        const lines = data.values.map((s, i) => {
-            const window = [s.startDate?.slice(0, 10), s.endDate?.slice(0, 10)].filter(Boolean).join(' -> ');
-            const goal = s.goal?.trim() ? ` | Goal: ${s.goal}` : '';
-            return `${startAt + i + 1}. [${s.id}] ${s.name} | ${s.state}${window ? ` | ${window}` : ''}${goal} | ${this.sprintUrl(boardId, s.id)}`;
-        });
-        const rangeEnd = startAt + data.values.length;
-        const page = data.isLast ? '' : ` (showing ${startAt + 1}-${rangeEnd}, use startAt=${rangeEnd} for next page)`;
-        return text(`Sprints for board ${boardId}${page}:\nBoard URL: ${this.boardUrl(boardId)}\n${lines.join('\n')}`);
-    }
-    async searchUsers(args) {
-        const params = new URLSearchParams({
-            username: args.query,
-            maxResults: String(args.maxResults ?? 10),
-        });
-        const data = await this.request('GET', `/user/search?${params}`);
-        if (!data || data.length === 0)
-            return text('No users found.');
-        const lines = data
-            .filter((u) => u.active)
-            .map((u, i) => `${i + 1}. ${u.displayName} (${u.name}) — ${u.emailAddress}`);
-        return text(`${lines.length} user(s) found:\n${lines.join('\n')}`);
-    }
-    async getIssueFields(issueKey) {
-        const data = await this.request('GET', `/issue/${encodeURIComponent(issueKey)}?fields=summary,status,issuetype`);
-        if (!data)
-            throw new Error(`Issue ${issueKey} not found`);
-        return {
-            summary: data.fields.summary,
-            status: data.fields.status.name,
-            type: data.fields.issuetype.name,
-        };
-    }
-    async getIssue(args) {
-        const fields = 'summary,description,status,assignee,priority,issuetype,labels,components';
-        const data = await this.request('GET', `/issue/${encodeURIComponent(args.issueKey)}?fields=${fields}`);
-        if (!data)
-            return text('Issue not found.');
-        const f = data.fields;
-        const lines = [
-            `Issue: ${data.key} — ${f.summary}`,
-            `URL:        ${this.issueUrl(data.key)}`,
-            `Status:     ${f.status.name}`,
-            `Type:       ${f.issuetype.name}`,
-            `Priority:   ${f.priority?.name ?? 'None'}`,
-            `Assignee:   ${f.assignee?.displayName ?? 'Unassigned'}`,
-            `Labels:     ${f.labels?.join(', ') || 'None'}`,
-            `Components: ${f.components?.map((c) => c.name).join(', ') || 'None'}`,
-            '',
-            'Description:',
-            f.description ?? '(no description)',
-        ];
-        return text(lines.join('\n'));
-    }
-    async issueOverview(args) {
-        const includeComments = args.includeComments ?? true;
-        const includeTransitions = args.includeTransitions ?? true;
-        const includeSprint = args.includeSprint ?? true;
-        const descriptionCap = args.fullDescription ? 0 : args.descriptionMaxChars ?? 2000;
-        const commentsMaxResults = args.commentsMaxResults ?? 10;
-        const commentsStartAt = args.commentsStartAt ?? 0;
-        const baseFields = 'summary,description,status,assignee,priority,issuetype,labels,components,parent,fixVersions,issuelinks,subtasks,attachment';
-        const epicFieldId = await this.getEpicLinkFieldId();
-        const fields = epicFieldId ? `${baseFields},${epicFieldId}` : baseFields;
-        const issue = await this.request('GET', `/issue/${encodeURIComponent(args.issueKey)}?fields=${fields}`);
-        if (!issue)
-            return text('Issue not found.');
-        const f = issue.fields;
-        const epicLinkKey = epicFieldId && typeof f[epicFieldId] === 'string'
-            ? f[epicFieldId]
-            : undefined;
-        const lines = [
-            `Issue: ${issue.key} — ${f.summary}`,
-            `URL:        ${this.issueUrl(issue.key)}`,
-            `Status:     ${f.status.name}`,
-            `Type:       ${f.issuetype.name}`,
-            `Priority:   ${f.priority?.name ?? 'None'}`,
-            `Assignee:   ${f.assignee?.displayName ?? 'Unassigned'}`,
-            `Labels:     ${f.labels?.join(', ') || 'None'}`,
-            `Components: ${f.components?.map((c) => c.name).join(', ') || 'None'}`,
-            ...(f.parent ? [`Parent:     [${f.parent.key}] ${f.parent.fields.summary} (${f.parent.fields.issuetype.name})`] : []),
-            ...(epicLinkKey ? [`Epic Link:  ${epicLinkKey}`] : []),
-            ...(f.fixVersions?.length ? [`Fix Vers:   ${f.fixVersions.map((v) => v.name).join(', ')}`] : []),
-            ...(f.subtasks?.length ? [`Subtasks:   ${f.subtasks.map((s) => `[${s.key}] ${s.fields.summary} (${s.fields.status.name})`).join(', ')}`] : []),
-            ...(f.issuelinks?.length ? [
-                `Links:      ${f.issuelinks.map((l) => {
-                    if (l.outwardIssue)
-                        return `${l.type.outward} → [${l.outwardIssue.key}] ${l.outwardIssue.fields.summary}`;
-                    if (l.inwardIssue)
-                        return `${l.type.inward} ← [${l.inwardIssue.key}] ${l.inwardIssue.fields.summary}`;
-                    return l.type.name;
-                }).join('; ')}`,
-            ] : []),
-        ];
-        if (includeSprint) {
-            try {
-                const agileIssue = await this.requestAgile('GET', `/issue/${encodeURIComponent(args.issueKey)}?fields=sprint,closedSprints`);
-                const activeSprint = agileIssue?.fields?.sprint;
-                const closedSprints = agileIssue?.fields?.closedSprints ?? [];
-                if (activeSprint) {
-                    lines.push(`Sprint:     [${activeSprint.id}] ${activeSprint.name} (${activeSprint.state})`);
-                }
-                else {
-                    lines.push('Sprint:     None');
-                }
-                if (closedSprints.length > 0) {
-                    const closed = closedSprints.slice(0, 5).map((s) => `[${s.id}] ${s.name}`).join(', ');
-                    const more = closedSprints.length > 5 ? ` (+${closedSprints.length - 5} more)` : '';
-                    lines.push(`History:    ${closed}${more}`);
-                }
-            }
-            catch (err) {
-                lines.push(`Sprint:     unavailable (${err.message})`);
-            }
-        }
-        if (includeTransitions) {
-            const transitions = await this.request('GET', `/issue/${encodeURIComponent(args.issueKey)}/transitions`);
-            const names = (transitions?.transitions ?? []).map((t) => `${t.name} -> ${t.to.name}`);
-            lines.push(`Transitions: ${names.length > 0 ? names.join(', ') : '(none)'}`);
-        }
-        lines.push('', 'Description:', f.description ? capText(f.description, descriptionCap) : '(no description)');
-        if (f.attachment?.length) {
-            lines.push('', `Attachments: ${f.attachment.length}`);
-            for (const att of f.attachment) {
-                const mt = att.mimeType ?? 'application/octet-stream';
-                lines.push(`  #${att.id} ${att.filename} (${mt}, ${formatBytes(att.size)})`);
-            }
-            lines.push('Use jira_get_attachment with attachmentId to view contents.');
-        }
-        if (includeComments) {
-            const comments = await this.request('GET', `/issue/${encodeURIComponent(args.issueKey)}/comment?startAt=${commentsStartAt}&maxResults=${commentsMaxResults}`);
-            const items = comments?.comments ?? [];
-            const total = comments?.total ?? 0;
-            const page = comments ? pagination(total, commentsStartAt, items.length) : '';
-            lines.push('', `Comments: ${total}${page}`);
-            if (items.length === 0) {
-                lines.push('(none)');
-            }
-            else {
-                for (const c of items) {
-                    const date = c.created.slice(0, 10);
-                    lines.push(`--- #${c.id} ${c.author.displayName} (${date}) ---`, c.body, '');
-                }
-            }
-        }
-        return text(lines.join('\n').trimEnd());
-    }
-    async boardOverview(args) {
-        const includeIssues = args.includeIssues ?? true;
-        const sprintMaxResults = args.sprintMaxResults ?? 10;
-        const sprintStartAt = args.sprintStartAt ?? 0;
-        const issueMaxResults = args.issueMaxResults ?? 25;
-        const issueStartAt = args.issueStartAt ?? 0;
-        const board = await this.requestAgile('GET', `/board/${args.boardId}`);
-        const sprintParams = new URLSearchParams({
-            maxResults: String(sprintMaxResults),
-            startAt: String(sprintStartAt),
-        });
-        if (args.sprintState) {
-            sprintParams.set('state', args.sprintState);
-        }
-        else {
-            sprintParams.set('state', 'active,future');
-        }
-        const sprints = await this.requestAgile('GET', `/board/${args.boardId}/sprint?${sprintParams}`);
-        if (!sprints || sprints.values.length === 0) {
-            return text(`Board ${args.boardId}${board?.name ? ` (${board.name})` : ''}: no matching sprints.`);
-        }
-        const issueFilterClauses = [];
-        if (args.assignee)
-            issueFilterClauses.push(`assignee = ${JSON.stringify(args.assignee)}`);
-        if (args.status)
-            issueFilterClauses.push(`status = ${JSON.stringify(args.status)}`);
-        const issueJql = issueFilterClauses.length > 0 ? issueFilterClauses.join(' AND ') : '';
-        const sprintIssueData = includeIssues
-            ? await Promise.all(sprints.values.map(async (sprint) => {
-                const params = new URLSearchParams({
-                    maxResults: String(issueMaxResults),
-                    startAt: String(issueStartAt),
-                    fields: 'summary,status,assignee,priority,issuetype',
-                });
-                if (issueJql)
-                    params.set('jql', issueJql);
-                const issues = await this.requestAgile('GET', `/sprint/${sprint.id}/issue?${params}`);
-                return { sprintId: sprint.id, issues };
-            }))
-            : [];
-        const issueBySprint = new Map(sprintIssueData.map((entry) => [entry.sprintId, entry.issues]));
-        const lines = [
-            `Board: [${args.boardId}] ${board?.name ?? '(unknown)'} | ${board?.type ?? '(unknown type)'}`,
-            `URL: ${this.boardUrl(args.boardId)}`,
-            `Sprints: ${sprints.values.length}`,
-            '',
-        ];
-        sprints.values.forEach((sprint, idx) => {
-            const window = [sprint.startDate?.slice(0, 10), sprint.endDate?.slice(0, 10)].filter(Boolean).join(' -> ');
-            lines.push(`${sprintStartAt + idx + 1}. [${sprint.id}] ${sprint.name} | ${sprint.state}${window ? ` | ${window}` : ''} | ${this.sprintUrl(args.boardId, sprint.id)}`);
-            if (sprint.goal?.trim()) {
-                lines.push(`   Goal: ${sprint.goal}`);
-            }
-            if (includeIssues) {
-                const issueData = issueBySprint.get(sprint.id);
-                const issues = issueData?.issues ?? [];
-                lines.push(`   Issues: ${issueData?.total ?? 0}`);
-                for (const issue of issues) {
-                    const assignee = issue.fields.assignee?.displayName ?? 'Unassigned';
-                    lines.push(`   - [${issue.key}] ${issue.fields.summary} | ${issue.fields.status.name} | ${assignee} | ${this.issueUrl(issue.key)}`);
-                }
-                if ((issueData?.total ?? 0) > issues.length) {
-                    lines.push(`   ...and ${(issueData?.total ?? 0) - issues.length} more (adjust issueStartAt/issueMaxResults).`);
-                }
-            }
-            lines.push('');
-        });
-        const sprintRangeEnd = sprintStartAt + sprints.values.length;
-        if (!sprints.isLast) {
-            lines.push(`More sprints available: use sprintStartAt=${sprintRangeEnd}.`);
-        }
-        return text(lines.join('\n').trimEnd());
-    }
-    async createIssue(args) {
-        const data = await this.createIssueInternal(args);
-        if (!data)
-            return text('Issue created.');
-        const url = this.issueUrl(data.key);
-        if (args.sprintId !== undefined) {
-            await this.addIssuesToSprintInternal(args.sprintId, [data.key]);
-            return text(`Created ${data.key} and added it to sprint ${args.sprintId}.\n${url}`);
-        }
-        return text(`Created ${data.key}.\n${url}`);
-    }
-    async updateIssue(args) {
-        const hasFieldUpdates = await this.updateIssueFieldsInternal(args);
-        if (!hasFieldUpdates && args.sprintId === undefined)
-            return text('Nothing to update.');
-        if (args.sprintId !== undefined) {
-            await this.addIssuesToSprintInternal(args.sprintId, [args.issueKey]);
-        }
-        if (hasFieldUpdates && args.sprintId !== undefined) {
-            return text(`Updated ${args.issueKey} and added it to sprint ${args.sprintId}.\n${this.issueUrl(args.issueKey)}`);
-        }
-        if (hasFieldUpdates) {
-            return text(`Updated ${args.issueKey}.\n${this.issueUrl(args.issueKey)}`);
-        }
-        return text(`Added ${args.issueKey} to sprint ${args.sprintId}.\n${this.issueUrl(args.issueKey)}`);
-    }
-    async addIssuesToSprint(args) {
-        const keys = new Set();
-        if (args.issueKey?.trim())
-            keys.add(args.issueKey.trim());
-        for (const issueKey of args.issueKeys ?? []) {
-            const trimmed = issueKey.trim();
-            if (trimmed)
-                keys.add(trimmed);
-        }
-        if (keys.size === 0) {
-            throw new Error('Provide issueKey or issueKeys with at least one Jira issue key.');
-        }
-        const issueKeys = Array.from(keys);
-        await this.addIssuesToSprintInternal(args.sprintId, issueKeys);
-        if (issueKeys.length === 1) {
-            return text(`Added ${issueKeys[0]} to sprint ${args.sprintId}.\n${this.issueUrl(issueKeys[0])}`);
-        }
-        const lines = [
-            `Added ${issueKeys.length} issue(s) to sprint ${args.sprintId}.`,
-            ...issueKeys.map((issueKey) => `${issueKey}: ${this.issueUrl(issueKey)}`),
-        ];
-        return text(lines.join('\n'));
-    }
-    async mutateIssue(args) {
-        let issueKey = args.issueKey?.trim();
-        const actions = [];
-        if (args.create) {
-            const created = await this.createIssueInternal(args.create);
-            if (!created)
-                throw new Error('Issue creation did not return an issue key.');
-            issueKey = created.key;
-            actions.push('created issue');
-        }
-        if (!issueKey) {
-            throw new Error('Provide issueKey, or provide create with issueType and summary.');
-        }
-        if (args.update) {
-            const updated = await this.updateIssueFieldsInternal({ issueKey, ...args.update });
-            if (updated)
-                actions.push('updated fields');
-        }
-        if (args.sprintId !== undefined) {
-            await this.addIssuesToSprintInternal(args.sprintId, [issueKey]);
-            actions.push(`added to sprint ${args.sprintId}`);
-        }
-        if (args.removeFromSprint) {
-            await this.requestAgile('POST', '/backlog/issue', { issues: [issueKey] });
-            actions.push('moved to backlog');
-        }
-        if (args.transitionId || args.transitionName) {
-            const transitionId = await this.resolveTransitionId(issueKey, args.transitionId, args.transitionName);
-            await this.transitionIssueInternal(issueKey, transitionId);
-            actions.push(`transitioned via ${transitionId}`);
-        }
-        if (args.comment !== undefined) {
-            await this.request('POST', `/issue/${encodeURIComponent(issueKey)}/comment`, { body: validateCommentBody(args.comment) });
-            actions.push('added comment');
-        }
-        const warnings = [];
-        if (args.link) {
-            if (!(await this.getIssueLinkingEnabled())) {
-                warnings.push(`issue linking is disabled in this Jira instance — add the link manually`);
-            }
-            else {
-                const dir = args.link.direction ?? 'outward';
-                await this.request('POST', '/issueLink', {
-                    type: { name: args.link.linkType },
-                    outwardIssue: { key: dir === 'outward' ? issueKey : args.link.targetIssueKey },
-                    inwardIssue: { key: dir === 'outward' ? args.link.targetIssueKey : issueKey },
-                });
-                actions.push(`linked ${args.link.linkType} → ${args.link.targetIssueKey}`);
-            }
-        }
-        if (args.worklog) {
-            const wBody = { timeSpent: args.worklog.timeSpent };
-            if (args.worklog.comment)
-                wBody.comment = args.worklog.comment;
-            if (args.worklog.started)
-                wBody.started = args.worklog.started;
-            await this.request('POST', `/issue/${encodeURIComponent(issueKey)}/worklog`, wBody);
-            actions.push(`logged ${args.worklog.timeSpent}`);
-        }
-        if (actions.length === 0) {
-            return text('Nothing to mutate.');
-        }
-        const parts = [`Mutated ${issueKey}: ${actions.join(', ')}.`, this.issueUrl(issueKey)];
-        if (warnings.length)
-            parts.push(`Warnings: ${warnings.join('; ')}`);
-        return text(parts.join('\n'));
-    }
-    async getComments(args) {
-        const { issueKey, maxResults = 50, startAt = 0 } = args;
-        const data = await this.request('GET', `/issue/${encodeURIComponent(issueKey)}/comment?startAt=${startAt}&maxResults=${maxResults}`);
-        if (!data || data.comments.length === 0)
-            return text('No comments found.');
-        const blocks = data.comments.map((c) => {
-            const date = c.created.slice(0, 10);
-            return `--- #${c.id} ${c.author.displayName} (${date}) ---\n${c.body}`;
-        });
-        const page = pagination(data.total, startAt, data.comments.length);
-        return text(`${data.total} comment(s) on ${issueKey}${page}:\n\n${blocks.join('\n\n')}`);
-    }
-    async addComment(args) {
-        await this.request('POST', `/issue/${encodeURIComponent(args.issueKey)}/comment`, { body: validateCommentBody(args.body) });
-        return text(`Comment added to ${args.issueKey}.`);
-    }
-    async editComment(args) {
-        const commentId = String(args.commentId ?? '').trim();
-        if (!commentId || commentId === 'undefined' || commentId === 'null') {
-            throw new Error('commentId is required.');
-        }
-        const path = `/issue/${encodeURIComponent(args.issueKey)}/comment/${encodeURIComponent(commentId)}`;
-        const current = await this.request('GET', path);
-        if (!current)
-            throw new Error(`Comment ${commentId} not found on ${args.issueKey}.`);
-        await this.assertOwnComment(current);
-        await this.request('PUT', path, { body: validateCommentBody(args.body) });
-        return text(`Comment ${commentId} updated on ${args.issueKey}.`);
-    }
-    async deleteComment(args) {
-        const commentId = String(args.commentId ?? '').trim();
-        if (!commentId || commentId === 'undefined' || commentId === 'null') {
-            throw new Error('commentId is required.');
-        }
-        const path = `/issue/${encodeURIComponent(args.issueKey)}/comment/${encodeURIComponent(commentId)}`;
-        const current = await this.request('GET', path);
-        if (!current)
-            throw new Error(`Comment ${commentId} not found on ${args.issueKey}.`);
-        await this.assertOwnComment(current);
-        await this.request('DELETE', path);
-        return text(`Comment ${commentId} deleted from ${args.issueKey}.`);
-    }
-    async getBoards(args) {
-        const params = new URLSearchParams({
-            maxResults: String(args.maxResults ?? 25),
-            startAt: String(args.startAt ?? 0),
-        });
-        if (args.projectKey)
-            params.set('projectKeyOrId', args.projectKey);
-        const data = await this.requestAgile('GET', `/board?${params}`);
-        if (!data || data.values.length === 0)
-            return text('No boards found.');
-        const lines = data.values.map((b, i) => {
-            const projectHint = b.location?.projectKey ? ` [${b.location.projectKey}]` : '';
-            return `${(args.startAt ?? 0) + i + 1}. [${b.id}] ${b.name} (${b.type})${projectHint} | ${this.boardUrl(b.id)}`;
-        });
-        const page = data.isLast ? '' : ` (use startAt=${(args.startAt ?? 0) + data.values.length} for next page)`;
-        return text(`${data.values.length} board(s)${page}:\n${lines.join('\n')}`);
-    }
-    async getAttachment(args) {
-        const id = String(args.attachmentId ?? '').trim();
-        if (!id)
-            throw new Error('attachmentId is required.');
-        const meta = await this.request('GET', `/attachment/${encodeURIComponent(id)}`);
-        if (!meta)
-            throw new Error(`Attachment ${id} not found.`);
-        // saveTo path: stream response directly to disk to bypass the in-memory size cap and avoid double-buffering.
-        if (args.saveTo) {
-            const path = resolvePath(args.saveTo);
-            const res = await fetch(meta.content, {
-                method: 'GET',
-                headers: { Authorization: this.headers.Authorization },
-                signal: AbortSignal.timeout(300_000),
-            });
-            if (!res.ok) {
-                const errText = await res.text();
-                throw new Error(formatJiraError(res.status, 'GET', meta.content, parseJiraErrorDetails(errText)));
-            }
-            if (!res.body)
-                throw new Error(`Attachment #${id} response has no body.`);
-            await pipeline(Readable.fromWeb(res.body), createWriteStream(path));
-            const sizeLabel = meta.size ? formatBytes(meta.size) : 'unknown size';
-            return { content: [{ type: 'text', text: `Saved attachment #${id} (${meta.filename} — ${meta.mimeType ?? 'application/octet-stream'}, ${sizeLabel}) to ${path}` }] };
-        }
-        // Inline path enforces the 250 MB cap so we don't OOM on accidental huge fetches.
-        if (meta.size && meta.size > MAX_VIDEO_SOURCE_BYTES) {
-            throw new Error(`Attachment #${id} is ${formatBytes(meta.size)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
-        }
-        const res = await fetch(meta.content, {
-            method: 'GET',
-            headers: { Authorization: this.headers.Authorization },
-            signal: AbortSignal.timeout(60_000),
-        });
-        if (!res.ok) {
-            const errText = await res.text();
-            throw new Error(formatJiraError(res.status, 'GET', meta.content, parseJiraErrorDetails(errText)));
-        }
-        const declaredLength = parseInt(res.headers.get('content-length') ?? '0', 10);
-        if (declaredLength > MAX_VIDEO_SOURCE_BYTES) {
-            try {
-                await res.body?.cancel();
-            }
-            catch { /* ignore */ }
-            throw new Error(`Attachment #${id} is ${formatBytes(declaredLength)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
-        }
-        const buffer = Buffer.from(await res.arrayBuffer());
-        if (buffer.length > MAX_VIDEO_SOURCE_BYTES) {
-            throw new Error(`Attachment #${id} downloaded ${formatBytes(buffer.length)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
-        }
-        return buildAttachmentResult({
-            id,
-            filename: meta.filename,
-            mimeType: meta.mimeType ?? 'application/octet-stream',
-            buffer,
-            maxDimension: args.maxDimension,
-            quality: args.quality,
-            frames: args.frames,
-            start: args.start,
-            end: args.end,
-            mode: args.mode,
-            sceneThreshold: args.sceneThreshold,
-        });
-    }
-    async transitionIssue(args) {
-        const transitionId = await this.resolveTransitionId(args.issueKey, args.transitionId, args.transitionName);
-        await this.transitionIssueInternal(args.issueKey, transitionId);
-        return text(`Transitioned ${args.issueKey} using transition ${transitionId}.\n${this.issueUrl(args.issueKey)}`);
-    }
-    async listVersions(args) {
-        const projectKey = await this.resolveProjectKey(args.projectKey);
-        const data = await this.request('GET', `/project/${encodeURIComponent(projectKey)}/versions`);
-        const query = args.query?.trim();
-        const createHint = (name) => `Create it with: jira_version action=create projectKey=${projectKey} name="${name}"`;
-        if (!data || data.length === 0) {
-            if (query)
-                return text(`No versions in ${projectKey}. ${createHint(query)}`);
-            return text(`No versions in ${projectKey}.`);
-        }
-        const filtered = query
-            ? data.filter(v => v.name.toLowerCase().includes(query.toLowerCase()))
-            : data;
-        if (query && filtered.length === 0) {
-            return text(`No version matching "${query}" in ${projectKey} (${data.length} other version(s) exist). ${createHint(query)}`);
-        }
-        const sorted = [...filtered].sort((a, b) => {
-            if (a.released !== b.released)
-                return a.released ? 1 : -1;
-            if (a.archived !== b.archived)
-                return a.archived ? 1 : -1;
-            const ad = a.releaseDate ?? '';
-            const bd = b.releaseDate ?? '';
-            return bd.localeCompare(ad);
-        });
-        const limit = args.maxResults ?? sorted.length;
-        const shown = sorted.slice(0, limit);
-        const lines = shown.map((v, i) => {
-            const tags = [];
-            if (v.released)
-                tags.push('released');
-            if (v.archived)
-                tags.push('archived');
-            const tagStr = tags.length ? ` [${tags.join(', ')}]` : '';
-            const dateParts = [v.startDate ? `start ${v.startDate}` : '', v.releaseDate ? `release ${v.releaseDate}` : ''].filter(Boolean);
-            const dateStr = dateParts.length ? ` (${dateParts.join(', ')})` : '';
-            return `${i + 1}. [${v.id}] ${v.name}${tagStr}${dateStr}`;
-        });
-        const header = query
-            ? `${filtered.length} version(s) matching "${query}" in ${projectKey}:`
-            : `${filtered.length} version(s) in ${projectKey}:`;
-        const more = filtered.length > shown.length ? `\n...and ${filtered.length - shown.length} more (raise maxResults).` : '';
-        return text(`${header}\n${lines.join('\n')}${more}`);
-    }
-    async mutateVersion(args) {
-        const action = args.action ?? 'create';
-        if (action === 'create') {
-            const projectKey = await this.resolveProjectKey(args.projectKey);
-            const name = args.name?.trim();
-            if (!name)
-                throw new Error('name is required to create a version.');
-            const body = { project: projectKey, name };
-            if (args.description !== undefined)
-                body.description = args.description;
-            if (args.releaseDate)
-                body.releaseDate = args.releaseDate;
-            if (args.startDate)
-                body.startDate = args.startDate;
-            if (args.released !== undefined)
-                body.released = args.released;
-            if (args.archived !== undefined)
-                body.archived = args.archived;
-            const created = await this.request('POST', '/version', body);
-            if (!created)
-                throw new Error('Jira returned no body when creating version.');
-            return text(`Created version [${created.id}] ${created.name} in ${projectKey}.`);
-        }
-        const id = args.id?.trim();
-        if (!id)
-            throw new Error(`version id is required for action=${action}.`);
-        if (action === 'delete') {
-            await this.request('DELETE', `/version/${encodeURIComponent(id)}`);
-            return text(`Deleted version ${id}.`);
-        }
-        const body = {};
-        if (args.name !== undefined)
-            body.name = args.name;
-        if (args.description !== undefined)
-            body.description = args.description;
-        if (args.startDate !== undefined)
-            body.startDate = args.startDate;
-        if (args.releaseDate !== undefined)
-            body.releaseDate = args.releaseDate;
-        if (args.released !== undefined)
-            body.released = args.released;
-        if (args.archived !== undefined)
-            body.archived = args.archived;
-        if (action === 'release') {
-            body.released = true;
-            if (body.releaseDate === undefined)
-                body.releaseDate = new Date().toISOString().slice(0, 10);
-        }
-        else if (action === 'archive') {
-            body.archived = true;
-        }
-        if (Object.keys(body).length === 0) {
-            throw new Error('Nothing to update.');
-        }
-        const updated = await this.request('PUT', `/version/${encodeURIComponent(id)}`, body);
-        const label = updated ? `[${updated.id}] ${updated.name}` : id;
-        if (action === 'release')
-            return text(`Released version ${label} on ${body.releaseDate}.`);
-        if (action === 'archive')
-            return text(`Archived version ${label}.`);
-        return text(`Updated version ${label}.`);
-    }
-}