@jackwener/opencli 1.7.22 → 1.8.1

package/clis/jira/commands.test.js

@@ -0,0 +1,287 @@
+import { describe, expect, it, afterEach, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { __test__ as jiraSharedTest } from './shared.js';
+import './issue.js';
+import './search.js';
+import './comments.js';
+import './attachments.js';
+import './links.js';
+
+const ENV_KEYS = [
+    'ATLASSIAN_JIRA_BASE_URL',
+    'ATLASSIAN_DEPLOYMENT',
+    'ATLASSIAN_EMAIL',
+    'ATLASSIAN_API_TOKEN',
+    'ATLASSIAN_USERNAME',
+    'ATLASSIAN_PASSWORD',
+    'ATLASSIAN_PAT',
+];
+
+function clearEnv() {
+    for (const key of ENV_KEYS) delete process.env[key];
+}
+
+function setCloudEnv() {
+    clearEnv();
+    process.env.ATLASSIAN_JIRA_BASE_URL = 'https://team.atlassian.net';
+    process.env.ATLASSIAN_DEPLOYMENT = 'cloud';
+    process.env.ATLASSIAN_EMAIL = 'bot@example.com';
+    process.env.ATLASSIAN_API_TOKEN = 'secret';
+}
+
+function jsonResponse(body) {
+    return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+}
+
+afterEach(() => {
+    clearEnv();
+    vi.unstubAllGlobals();
+});
+
+describe('jira commands', () => {
+    it('registers non-browser REST commands', () => {
+        for (const name of ['issue', 'search', 'comments', 'attachments', 'links']) {
+            const cmd = getRegistry().get(`jira/${name}`);
+            expect(cmd).toBeDefined();
+            expect(cmd.browser).toBe(false);
+            expect(cmd.strategy).toBe('public');
+        }
+    });
+
+    it('normalizes a Cloud issue into agent-friendly context', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async (url) => {
+            expect(String(url)).toContain('/rest/api/3/issue/PROJ-1?');
+            return jsonResponse({
+                id: '10001',
+                key: 'PROJ-1',
+                fields: {
+                    summary: 'Checkout fails',
+                    issuetype: { name: 'Bug' },
+                    status: { name: 'In Progress' },
+                    priority: { name: 'High' },
+                    labels: ['prod'],
+                    description: {
+                        type: 'doc',
+                        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Payment fails' }] }],
+                    },
+                    comment: {
+                        total: 1,
+                        comments: [{
+                            id: 'c1',
+                            author: { displayName: 'Alice' },
+                            created: '2026-05-01T00:00:00.000+0000',
+                            body: { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Needs RCA' }] }] },
+                        }],
+                    },
+                    attachment: [{ id: 'a1', filename: 'log.txt', mimeType: 'text/plain', size: 12, content: 'https://team.atlassian.net/secure/attachment/a1/log.txt' }],
+                    issuelinks: [{ type: { name: 'Blocks' }, outwardIssue: { key: 'PROJ-2' } }],
+                    fixVersions: [{ name: '1.2.3' }],
+                    created: '2026-05-01T00:00:00.000+0000',
+                    updated: '2026-05-02T00:00:00.000+0000',
+                },
+            });
+        }));
+        const cmd = getRegistry().get('jira/issue');
+        const rows = await cmd.func({ key: 'proj-1' });
+        expect(rows[0]).toMatchObject({
+            key: 'PROJ-1',
+            summary: 'Checkout fails',
+            issueType: 'Bug',
+            status: 'In Progress',
+            labels: ['prod'],
+            url: 'https://team.atlassian.net/browse/PROJ-1',
+        });
+        expect(rows[0].description.markdown).toBe('Payment fails');
+        expect(rows[0].comments[0].markdown).toBe('Needs RCA');
+        expect(rows[0].attachments[0].filename).toBe('log.txt');
+        expect(rows[0].linkedIssues[0]).toEqual({ key: 'PROJ-2', type: 'Blocks', direction: 'outward' });
+    });
+
+    it('fails typed when Jira issue payload is missing stable issue identity', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ fields: { summary: 'No key' } })));
+        const cmd = getRegistry().get('jira/issue');
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('fails typed when Jira issue nested collections have malformed shapes', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('jira/issue');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: { total: 1, comments: { id: 'c1' } },
+                attachment: [],
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: { total: 0, comments: [] },
+                attachment: { id: 'a1' },
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: null,
+                attachment: [],
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: { total: 0, comments: [] },
+                attachment: null,
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects invalid Jira issue keys before remote requests', async () => {
+        expect(() => jiraSharedTest.requireIssueKey('notakey')).toThrow(/Invalid Jira issue key/);
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('jira/issue');
+        await expect(cmd.func({ key: 'notakey' })).rejects.toMatchObject({ code: 'ARGUMENT' });
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('fetches full comments when issue inline comments are truncated', async () => {
+        setCloudEnv();
+        const fetchMock = vi.fn(async (url) => {
+            const href = String(url);
+            if (href.includes('/comment?')) {
+                return jsonResponse({
+                    comments: [
+                        { id: 'c1', author: { displayName: 'Alice' }, created: '2026-05-01', body: 'one' },
+                        { id: 'c2', author: { displayName: 'Bob' }, created: '2026-05-02', body: 'two' },
+                    ],
+                });
+            }
+            return jsonResponse({
+                id: '10001',
+                key: 'PROJ-1',
+                fields: {
+                    summary: 'Checkout fails',
+                    labels: [],
+                    comment: {
+                        total: 2,
+                        comments: [{ id: 'c1', author: { displayName: 'Alice' }, created: '2026-05-01', body: 'one' }],
+                    },
+                    attachment: [],
+                    issuelinks: [],
+                },
+            });
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('jira/issue');
+        const rows = await cmd.func({ key: 'PROJ-1', 'comments-limit': 10 });
+        expect(rows[0].comments.map((comment) => comment.id)).toEqual(['c1', 'c2']);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('uses Data Center search endpoint and payload', async () => {
+        clearEnv();
+        process.env.ATLASSIAN_JIRA_BASE_URL = 'https://jira.example.com';
+        process.env.ATLASSIAN_DEPLOYMENT = 'datacenter';
+        process.env.ATLASSIAN_USERNAME = 'bot';
+        process.env.ATLASSIAN_PASSWORD = 'secret';
+        const fetchMock = vi.fn(async (url, init) => {
+            expect(String(url)).toBe('https://jira.example.com/rest/api/2/search');
+            expect(init.method).toBe('POST');
+            expect(JSON.parse(init.body)).toMatchObject({
+                jql: 'project = PROJ',
+                startAt: 0,
+                maxResults: 5,
+            });
+            return jsonResponse({
+                issues: [{
+                    id: '1',
+                    key: 'PROJ-1',
+                    fields: {
+                        summary: 'Task',
+                        status: { name: 'Done' },
+                        updated: '2026-05-03T00:00:00.000+0000',
+                    },
+                }],
+            });
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('jira/search');
+        const rows = await cmd.func({ jql: 'project = PROJ', limit: 5 });
+        expect(rows).toEqual([
+            expect.objectContaining({ key: 'PROJ-1', summary: 'Task', status: 'Done' }),
+        ]);
+    });
+
+    it('separates Jira search empty results from malformed search payloads', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('jira/search');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ issues: [] })));
+        await expect(cmd.func({ jql: 'project = NONE' })).rejects.toBeInstanceOf(EmptyResultError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ values: [] })));
+        await expect(cmd.func({ jql: 'project = PROJ' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps rendered comments to Markdown', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            comments: [{
+                id: 'c1',
+                author: { displayName: 'Bob' },
+                created: '2026-05-01',
+                renderedBody: '<p>Fixed<br/>Ready for QA</p>',
+            }],
+        })));
+        const cmd = getRegistry().get('jira/comments');
+        const rows = await cmd.func({ key: 'PROJ-1', limit: 1 });
+        expect(rows[0]).toMatchObject({ id: 'c1', author: 'Bob' });
+        expect(rows[0].markdown).toContain('Fixed');
+        expect(rows[0].markdown).toContain('Ready for QA');
+    });
+
+    it('fails typed when Jira comment rows lack stable comment ids', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            comments: [{ author: { displayName: 'Bob' }, created: '2026-05-01', body: 'body' }],
+        })));
+        const cmd = getRegistry().get('jira/comments');
+        await expect(cmd.func({ key: 'PROJ-1', limit: 1 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('separates no Jira attachments from malformed attachment payloads', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('jira/attachments');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ id: '1', key: 'PROJ-1', fields: { attachment: [] } })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(EmptyResultError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ id: '1', key: 'PROJ-1', fields: {} })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});

package/clis/jira/comments.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchComments, jiraConfig, jiraRowsOrEmpty, normalizeComment, parseJiraLimit, requireIssueKey } from './shared.js';
+
+cli({
+    site: 'jira',
+    name: 'comments',
+    access: 'read',
+    description: 'Jira issue comments as Markdown',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+        { name: 'limit', type: 'int', default: 50, help: 'Max comments to return (1-100)' },
+    ],
+    columns: ['id', 'author', 'created', 'updated', 'markdown'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const limit = parseJiraLimit(args.limit, 50, 100);
+        const comments = await fetchComments(config, key, limit);
+        return jiraRowsOrEmpty(
+            comments.map(normalizeComment),
+            `jira comments ${key}`,
+            `Jira issue ${key} has no comments.`,
+        );
+    },
+});

package/clis/jira/issue.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchComments, fetchIssue, jiraConfig, normalizeJiraIssue, requireIssueKey } from './shared.js';
+
+cli({
+    site: 'jira',
+    name: 'issue',
+    access: 'read',
+    description: 'Jira issue detail normalized for agents (description, comments, attachments, links)',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+        { name: 'comments-limit', type: 'int', default: 100, help: 'Max comments to include (1-100)' },
+    ],
+    columns: ['key', 'summary', 'issueType', 'status', 'priority', 'assignee', 'updated', 'url'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const issue = await fetchIssue(config, key);
+        const inlineComments = issue?.fields?.comment?.comments;
+        const total = Number(issue?.fields?.comment?.total ?? inlineComments?.length ?? 0);
+        const comments = total > (inlineComments?.length ?? 0)
+            ? await fetchComments(config, key, args['comments-limit'])
+            : inlineComments;
+        return [normalizeJiraIssue(issue, config, { comments })];
+    },
+});

package/clis/jira/links.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchIssue, jiraConfig, jiraRowsOrEmpty, normalizeIssueLink, requireIssueKey } from './shared.js';
+import { requirePayloadArray } from '../_atlassian/shared.js';
+
+cli({
+    site: 'jira',
+    name: 'links',
+    access: 'read',
+    description: 'Jira issue links',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+    ],
+    columns: ['key', 'type', 'direction'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const issue = await fetchIssue(config, key, ['issuelinks']);
+        const links = requirePayloadArray(issue.fields?.issuelinks, `jira links ${key}`);
+        return jiraRowsOrEmpty(
+            links.map(normalizeIssueLink),
+            `jira links ${key}`,
+            `Jira issue ${key} has no linked issues.`,
+        );
+    },
+});

package/clis/jira/search.js

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { jiraConfig, issueSummaryRow, jiraRowsOrEmpty, parseJiraLimit } from './shared.js';
+import { atlassianRequest, requirePayloadArray, requirePayloadObject, requireString } from '../_atlassian/shared.js';
+
+function searchPath(config) {
+    return config.deployment === 'cloud' ? '/rest/api/3/search/jql' : '/rest/api/2/search';
+}
+
+function searchPayload(config, jql, limit) {
+    const fields = ['summary', 'issuetype', 'status', 'priority', 'assignee', 'updated'];
+    if (config.deployment === 'cloud') return { jql, maxResults: limit, fields };
+    return { jql, startAt: 0, maxResults: limit, fields };
+}
+
+cli({
+    site: 'jira',
+    name: 'search',
+    access: 'read',
+    description: 'Search Jira issues with JQL',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'jql', positional: true, required: true, help: 'JQL query, e.g. "project = PROJ order by updated desc"' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max issues to return (1-100)' },
+    ],
+    columns: ['key', 'summary', 'issueType', 'status', 'priority', 'assignee', 'updated', 'url'],
+    func: async (args) => {
+        const config = jiraConfig();
+        const jql = requireString(args.jql, 'JQL');
+        const limit = parseJiraLimit(args.limit, 20, 100);
+        const data = await atlassianRequest(config, searchPath(config), {
+            method: 'POST',
+            body: searchPayload(config, jql, limit),
+            label: 'jira search',
+        });
+        const payload = requirePayloadObject(data, 'jira search');
+        const issues = requirePayloadArray(payload.issues, 'jira search issues');
+        return jiraRowsOrEmpty(
+            issues.map((issue) => issueSummaryRow(issue, config)),
+            'jira search',
+            `No Jira issues matched "${jql}".`,
+        );
+    },
+});
+
+export const __test__ = { searchPath, searchPayload };

package/clis/jira/shared.js

@@ -0,0 +1,256 @@
+import {
+    adfToMarkdown,
+    atlassianRequest,
+    getJiraConfig,
+    htmlToMarkdown,
+    parseLimit,
+    queryString,
+    requireNonEmptyRows,
+    requirePayloadArray,
+    requirePayloadObject,
+    requirePayloadString,
+    requireString,
+} from '../_atlassian/shared.js';
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+const DEFAULT_ISSUE_FIELDS = [
+    'summary',
+    'issuetype',
+    'status',
+    'priority',
+    'labels',
+    'description',
+    'comment',
+    'attachment',
+    'issuelinks',
+    'fixVersions',
+    'versions',
+    'components',
+    'project',
+    'reporter',
+    'assignee',
+    'created',
+    'updated',
+];
+
+function jiraApiPrefix(config) {
+    return `/rest/api/${config.deployment === 'cloud' ? '3' : '2'}`;
+}
+
+export function jiraApiPath(config, resource, params) {
+    return `${jiraApiPrefix(config)}${resource.startsWith('/') ? resource : `/${resource}`}${params ? queryString(params) : ''}`;
+}
+
+export async function jiraRequest(config, resource, options = {}) {
+    return atlassianRequest(config, jiraApiPath(config, resource, options.params), options);
+}
+
+function configuredFieldNames() {
+    return {
+        acceptanceCriteria: process.env.ATLASSIAN_JIRA_ACCEPTANCE_FIELD?.trim() || '',
+        sprint: process.env.ATLASSIAN_JIRA_SPRINT_FIELD?.trim() || '',
+        storyPoints: process.env.ATLASSIAN_JIRA_STORY_POINTS_FIELD?.trim() || '',
+    };
+}
+
+function issueFields(extraFields = []) {
+    const configured = Object.values(configuredFieldNames()).filter(Boolean);
+    return [...new Set([...DEFAULT_ISSUE_FIELDS, ...configured, ...extraFields.filter(Boolean)])].join(',');
+}
+
+export function parseJiraLimit(value, fallback = 20, max = 100) {
+    return parseLimit(value, fallback, max, 'jira limit');
+}
+
+export function requireIssueKey(value) {
+    const key = requireString(value, 'Jira issue key');
+    if (!/^[A-Za-z][A-Za-z0-9_]+-\d+$/.test(key)) {
+        throw new ArgumentError(`Invalid Jira issue key: ${key}`, 'Expected a key like PROJECT-123.');
+    }
+    return key.toUpperCase();
+}
+
+function displayUser(user) {
+    if (!user || typeof user !== 'object') return '';
+    return String(user.displayName ?? user.name ?? user.emailAddress ?? user.accountId ?? '');
+}
+
+function valueName(value) {
+    if (!value) return '';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'object') return String(value.name ?? value.value ?? value.key ?? value.id ?? '');
+    return String(value);
+}
+
+function valueNames(values) {
+    return Array.isArray(values) ? values.map(valueName).filter(Boolean) : [];
+}
+
+export function jiraBodyToMarkdown(raw, rendered) {
+    if (rendered) return htmlToMarkdown(rendered);
+    if (raw && typeof raw === 'object') return adfToMarkdown(raw);
+    if (typeof raw === 'string') return raw.trim();
+    return '';
+}
+
+export function normalizeComment(comment) {
+    const row = requirePayloadObject(comment, 'jira comment');
+    return {
+        id: requirePayloadString(row.id, 'comment id', 'jira comment'),
+        author: displayUser(row.author),
+        created: row.created ? String(row.created) : '',
+        updated: row.updated ? String(row.updated) : undefined,
+        markdown: jiraBodyToMarkdown(row.body, row.renderedBody),
+    };
+}
+
+export function normalizeAttachment(attachment) {
+    const row = requirePayloadObject(attachment, 'jira attachment');
+    return {
+        id: requirePayloadString(row.id, 'attachment id', 'jira attachment'),
+        filename: requirePayloadString(row.filename, 'filename', 'jira attachment'),
+        mimeType: row.mimeType ? String(row.mimeType) : undefined,
+        size: row.size != null ? Number(row.size) : undefined,
+        url: requirePayloadString(row.content ?? row.self, 'attachment url', 'jira attachment'),
+    };
+}
+
+export function normalizeIssueLink(link) {
+    const row = requirePayloadObject(link, 'jira issue link');
+    const outward = row.outwardIssue;
+    const inward = row.inwardIssue;
+    const issue = outward ?? inward ?? {};
+    const key = requirePayloadString(issue.key, 'linked issue key', 'jira issue link');
+    return {
+        key,
+        type: String(row.type?.name ?? (outward ? row.type?.outward : row.type?.inward) ?? ''),
+        direction: outward ? 'outward' : 'inward',
+    };
+}
+
+function customValueToMarkdown(value) {
+    if (!value) return '';
+    if (typeof value === 'string') return value.trim();
+    if (value && typeof value === 'object' && value.type === 'doc') return adfToMarkdown(value);
+    if (Array.isArray(value)) return value.map(valueName).filter(Boolean).join(', ');
+    return valueName(value);
+}
+
+function inlineComments(fields, key, options) {
+    if (options.comments !== undefined) return requirePayloadArray(options.comments, `jira issue ${key} comments`);
+    if (options.requireNestedCollections === false) return [];
+    const commentBlock = requirePayloadObject(fields.comment, `jira issue ${key} comment field`);
+    return requirePayloadArray(commentBlock.comments, `jira issue ${key} comment field comments`);
+}
+
+export function normalizeJiraIssue(issue, config, options = {}) {
+    const row = requirePayloadObject(issue, 'jira issue');
+    const key = requirePayloadString(row.key, 'issue key', 'jira issue');
+    const fields = requirePayloadObject(row.fields, `jira issue ${key} fields`);
+    const rendered = row.renderedFields && typeof row.renderedFields === 'object' && !Array.isArray(row.renderedFields)
+        ? row.renderedFields
+        : {};
+    const custom = configuredFieldNames();
+    const comments = inlineComments(fields, key, options);
+    const requireNestedCollections = options.requireNestedCollections !== false;
+    const attachments = requireNestedCollections
+        ? requirePayloadArray(fields.attachment, `jira issue ${key} attachment field`)
+        : [];
+    const issueLinks = requireNestedCollections
+        ? requirePayloadArray(fields.issuelinks, `jira issue ${key} issuelinks field`)
+        : [];
+    const normalized = {
+        key,
+        id: row.id != null ? String(row.id) : '',
+        url: `${config.baseUrl}/browse/${key}`,
+        summary: String(fields.summary ?? ''),
+        issueType: valueName(fields.issuetype) || undefined,
+        status: valueName(fields.status) || undefined,
+        priority: valueName(fields.priority) || undefined,
+        project: valueName(fields.project) || undefined,
+        reporter: displayUser(fields.reporter) || undefined,
+        assignee: displayUser(fields.assignee) || undefined,
+        labels: Array.isArray(fields.labels) ? fields.labels.map(String) : [],
+        description: {
+            raw: fields.description ?? null,
+            markdown: jiraBodyToMarkdown(fields.description, rendered.description),
+        },
+        comments: comments.map(normalizeComment),
+        attachments: attachments.map(normalizeAttachment),
+        linkedIssues: issueLinks.map(normalizeIssueLink),
+        fixVersions: valueNames(fields.fixVersions),
+        affectedVersions: valueNames(fields.versions),
+        components: valueNames(fields.components),
+        created: fields.created ? String(fields.created) : undefined,
+        updated: fields.updated ? String(fields.updated) : undefined,
+    };
+    if (custom.acceptanceCriteria && fields[custom.acceptanceCriteria] !== undefined) {
+        normalized.acceptanceCriteria = {
+            raw: fields[custom.acceptanceCriteria],
+            markdown: customValueToMarkdown(fields[custom.acceptanceCriteria]),
+        };
+    }
+    if (custom.sprint && fields[custom.sprint] !== undefined) {
+        normalized.sprint = customValueToMarkdown(fields[custom.sprint]);
+    }
+    if (custom.storyPoints && fields[custom.storyPoints] !== undefined) {
+        normalized.storyPoints = Number(fields[custom.storyPoints]);
+    }
+    return normalized;
+}
+
+export function issueSummaryRow(issue, config) {
+    const normalized = normalizeJiraIssue(issue, config, { comments: [], requireNestedCollections: false });
+    return {
+        key: normalized.key,
+        summary: normalized.summary,
+        issueType: normalized.issueType,
+        status: normalized.status,
+        priority: normalized.priority,
+        assignee: normalized.assignee,
+        updated: normalized.updated,
+        url: normalized.url,
+    };
+}
+
+export async function fetchIssue(config, key, extraFields = []) {
+    const issue = await jiraRequest(config, `/issue/${encodeURIComponent(key)}`, {
+        params: {
+            fields: issueFields(extraFields),
+            expand: 'renderedFields',
+        },
+        label: `jira issue ${key}`,
+    });
+    return requirePayloadObject(issue, `jira issue ${key}`);
+}
+
+export async function fetchComments(config, key, limit = 100) {
+    const maxResults = parseJiraLimit(limit, 100, 100);
+    const data = await jiraRequest(config, `/issue/${encodeURIComponent(key)}/comment`, {
+        params: { startAt: 0, maxResults, expand: 'renderedBody' },
+        label: `jira comments ${key}`,
+    });
+    const payload = requirePayloadObject(data, `jira comments ${key}`);
+    return requirePayloadArray(payload.comments, `jira comments ${key}`);
+}
+
+export function jiraRowsOrEmpty(rows, label, hint) {
+    return requireNonEmptyRows(rows, label, hint);
+}
+
+export function jiraConfig() {
+    return getJiraConfig();
+}
+
+export const __test__ = {
+    configuredFieldNames,
+    fetchIssue,
+    issueSummaryRow,
+    jiraApiPath,
+    jiraBodyToMarkdown,
+    normalizeAttachment,
+    normalizeComment,
+    normalizeIssueLink,
+    normalizeJiraIssue,
+    requireIssueKey,
+};