& "quotes" 'apostrophe'"
+Content
+~~~`
+
+ expect(convertDetailsToExpandSyntax(input)).toBe(expected)
+ })
+ })
+
+ describe('markdownToAdf', () => {
+ test('returns empty doc for empty input', () => {
+ expect(markdownToAdf('')).toEqual({ type: 'doc', version: 1, content: [] })
+ })
+
+ test('returns empty doc for null input', () => {
+ expect(markdownToAdf(null as unknown as string)).toEqual({ type: 'doc', version: 1, content: [] })
+ })
+
+ test('returns empty doc for undefined input', () => {
+ expect(markdownToAdf(undefined as unknown as string)).toEqual({ type: 'doc', version: 1, content: [] })
+ })
+
+ test('converts plain text to ADF', () => {
+ const result = markdownToAdf('Hello world')
+ expect(result).toHaveProperty('type', 'doc')
+ expect(result).toHaveProperty('version', 1)
+ expect(result).toHaveProperty('content')
+ })
+
+ test('converts details/summary to ADF expand node', () => {
+ const input = `
+Click to expand
+Hidden content
+ `
+
+ const result = markdownToAdf(input)
+ expect(result).toHaveProperty('type', 'doc')
+ expect(result).toHaveProperty('content')
+
+ // The ADF should contain an expand node (since the preprocessing converts to expand syntax)
+ const content = (result as { content: unknown[] }).content
+ expect(content.length).toBeGreaterThan(0)
+
+ // Find the expand node in the content
+ const hasExpandNode = content.some((node: unknown) => {
+ return (node as { type: string }).type === 'expand'
+ })
+ expect(hasExpandNode).toBe(true)
+ })
+
+ test('converts nested details/summary correctly', () => {
+ const input = `
+Outer
+Outer content
+
+Inner
+Inner content
+
+ `
+
+ const result = markdownToAdf(input)
+ expect(result).toHaveProperty('type', 'doc')
+
+ // Should have expand nodes
+ const content = (result as { content: unknown[] }).content
+ const expandNodes = content.filter((node: unknown) => (node as { type: string }).type === 'expand')
+ expect(expandNodes.length).toBeGreaterThanOrEqual(1)
+ })
+
+ test('preserves regular markdown content alongside details blocks', () => {
+ const input = `# Heading
+
+Some regular text
+
+
+Expandable
+Hidden content
+
+
+More text`
+
+ const result = markdownToAdf(input)
+ expect(result).toHaveProperty('type', 'doc')
+
+ const content = (result as { content: unknown[] }).content
+ // Should have multiple content nodes (heading, paragraphs, expand)
+ expect(content.length).toBeGreaterThan(1)
+ })
+
+ test('handles markdown with emoji in summary', () => {
+ const input = `
+📋 Complete Context
+Content here
+ `
+
+ const result = markdownToAdf(input)
+ expect(result).toHaveProperty('type', 'doc')
+
+ // Should have an expand node with the title including emoji
+ const content = (result as { content: unknown[] }).content
+ const expandNode = content.find((node: unknown) => (node as { type: string }).type === 'expand')
+ expect(expandNode).toBeDefined()
+ expect((expandNode as { attrs: { title: string } }).attrs.title).toBe('📋 Complete Context')
+ })
+
+ // Tests for code mark sanitization - ADF spec requires code marks to be standalone
+ describe('code mark sanitization', () => {
+ test('code mark only remains unchanged', () => {
+ const input = 'Some `code` here'
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ expect(codeNodes[0].text).toBe('code')
+ })
+
+ test('code with bold mark - removes bold, keeps only code', () => {
+ const input = '**bold `code`**'
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ expect(codeNodes[0].text).toBe('code')
+ })
+
+ test('code with italic mark - removes italic, keeps only code', () => {
+ const input = '*italic `code`*'
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ expect(codeNodes[0].text).toBe('code')
+ })
+
+ test('code with multiple marks (bold + italic) - removes all, keeps only code', () => {
+ const input = '***bold italic `code`***'
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ expect(codeNodes[0].text).toBe('code')
+ })
+
+ test('code inside link - removes link mark, keeps only code', () => {
+ const input = '[`code link`](https://example.com)'
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ expect(codeNodes[0].text).toBe('code link')
+ })
+
+ test('nested content with code marks is recursively sanitized', () => {
+ // Blockquote with bold code inside
+ const input = `> **bold \`code\`** in blockquote`
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ })
+
+ test('no code marks - text remains unchanged', () => {
+ const input = '**bold** and *italic* text'
+ const result = markdownToAdf(input) as AdfNode
+
+ // Should have bold and italic marks, but no code
+ const codeNodes = findTextNodesWithCodeMark(result)
+ expect(codeNodes.length).toBe(0)
+
+ // The bold and italic text should still have their marks
+ const content = result.content || []
+ expect(content.length).toBeGreaterThan(0)
+ })
+
+ test('multiple text nodes - only code-marked nodes are affected', () => {
+ const input = '**bold** and `code` and *italic*'
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ // Only one code node
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+
+ // Other marks should be preserved
+ const content = result.content || []
+ const paragraph = content[0]
+ const textNodes = (paragraph?.content || []) as AdfNode[]
+
+ // Find the bold text node
+ const boldNode = textNodes.find(
+ (node) => node.type === 'text' && node.marks?.some((m) => m.type === 'strong')
+ )
+ expect(boldNode).toBeDefined()
+
+ // Find the italic text node
+ const italicNode = textNodes.find(
+ (node) => node.type === 'text' && node.marks?.some((m) => m.type === 'em')
+ )
+ expect(italicNode).toBeDefined()
+ })
+
+ test('handles text with no marks array', () => {
+ const input = 'Plain text with no formatting'
+ const result = markdownToAdf(input) as AdfNode
+
+ // Should not throw and should have content
+ expect(result.type).toBe('doc')
+ expect(result.content?.length).toBeGreaterThan(0)
+ })
+
+ test('handles deeply nested structure with code marks', () => {
+ // List with nested content containing code
+ const input = `- Item with **\`code\`** inside`
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ expect(codeNodes.length).toBe(1)
+ expect(codeNodes[0].marks).toEqual([{ type: 'code' }])
+ })
+
+ test('mixed content - code inside various formatting preserved correctly', () => {
+ const input = `Text with **bold \`code1\`** and *italic \`code2\`* and plain \`code3\``
+ const result = markdownToAdf(input) as AdfNode
+ const codeNodes = findTextNodesWithCodeMark(result)
+
+ // All three code nodes should only have code marks
+ expect(codeNodes.length).toBe(3)
+ for (const node of codeNodes) {
+ expect(node.marks).toEqual([{ type: 'code' }])
+ }
+ })
+ })
+ })
+})
diff --git a/src/lib/providers/jira/AdfMarkdownConverter.ts b/src/lib/providers/jira/AdfMarkdownConverter.ts
new file mode 100644
index 00000000..36f8ef46
--- /dev/null
+++ b/src/lib/providers/jira/AdfMarkdownConverter.ts
@@ -0,0 +1,118 @@
+// AdfMarkdownConverter - Converts between Atlassian Document Format (ADF) and Markdown
+// Uses extended-markdown-adf-parser for bidirectional conversion
+
+import { ADFDocument, Parser } from 'extended-markdown-adf-parser'
+
+const parser = new Parser()
+
+/**
+ * Represents a node in the ADF tree structure
+ */
+interface AdfNode {
+ type: string
+ content?: AdfNode[]
+ marks?: Array<{ type: string; attrs?: Record
}>
+ text?: string
+ attrs?: Record
+}
+
+/**
+ * Recursively traverse ADF tree and ensure code-marked text only has the code mark.
+ * ADF specification requires that code marks are standalone - no other marks allowed.
+ */
+function sanitizeCodeMarks(node: AdfNode): AdfNode {
+ // If node has marks and one of them is 'code', keep only the code mark
+ if (node.marks?.some((mark) => mark.type === 'code')) {
+ node.marks = [{ type: 'code' }]
+ }
+
+ // Recursively process child nodes
+ if (node.content && Array.isArray(node.content)) {
+ node.content = node.content.map((child) => sanitizeCodeMarks(child))
+ }
+
+ return node
+}
+
+/**
+ * Convert HTML details/summary blocks to ADF expand fence syntax
+ * The extended-markdown-adf-parser library supports ~~~expand title="..."~~~ syntax
+ * but not HTML tags
+ *
+ * @param markdown - Markdown string potentially containing HTML details/summary blocks
+ * @returns Markdown with details/summary converted to ADF expand fence syntax
+ */
+export function convertDetailsToExpandSyntax(markdown: string): string {
+ if (!markdown) return markdown
+
+ // Process from innermost to outermost to handle nesting correctly
+ let previousText = ''
+ let currentText = markdown
+
+ while (previousText !== currentText) {
+ previousText = currentText
+ // Match blocks with optional attributes on the tags
+ currentText = currentText.replace(
+ /]*>\s*]*>([\s\S]*?)<\/summary>([\s\S]*?)<\/details>/gi,
+ (_match, summary, content) => {
+ // Clean up the summary - trim whitespace and decode HTML entities
+ const cleanSummary = summary
+ .trim()
+ .replace(/</g, '<')
+ .replace(/>/g, '>')
+ .replace(/&/g, '&')
+ .replace(/"/g, '"')
+ .replace(/'/g, "'")
+
+ // Clean up the content - trim and normalize excessive blank lines
+ let cleanContent = content.trim()
+ cleanContent = cleanContent.replace(/\n{3,}/g, '\n\n')
+
+ // Build ADF expand fence syntax
+ if (cleanContent) {
+ return `~~~expand title="${cleanSummary}"\n${cleanContent}\n~~~`
+ } else {
+ return `~~~expand title="${cleanSummary}"\n~~~`
+ }
+ }
+ )
+ }
+
+ return currentText
+}
+
+/**
+ * Convert ADF (Atlassian Document Format) to Markdown
+ * Used when reading issue descriptions and comments from Jira
+ *
+ * @param adf - ADF object, string, null, or undefined
+ * @returns Markdown string
+ */
+export function adfToMarkdown(adf: unknown): string {
+ // Handle null/undefined
+ if (!adf) return ''
+
+ // Handle plain string (already text, not ADF)
+ if (typeof adf === 'string') return adf
+
+ // Convert ADF object to markdown
+ return parser.adfToMarkdown(adf as ADFDocument)
+}
+
+/**
+ * Convert Markdown to ADF (Atlassian Document Format)
+ * Used when writing issue descriptions and comments to Jira
+ *
+ * @param markdown - Markdown string
+ * @returns ADF object suitable for Jira API v3
+ */
+export function markdownToAdf(markdown: string): object {
+ if (!markdown) {
+ return { type: 'doc', version: 1, content: [] }
+ }
+ // Convert HTML details/summary to ADF expand syntax before parsing
+ const preprocessed = convertDetailsToExpandSyntax(markdown)
+ const adf = parser.markdownToAdf(preprocessed)
+ // Sanitize code marks - ensure code-marked text only has code mark
+ return sanitizeCodeMarks(adf as AdfNode)
+}
diff --git a/src/lib/providers/jira/JiraApiClient.ts b/src/lib/providers/jira/JiraApiClient.ts
new file mode 100644
index 00000000..063d4141
--- /dev/null
+++ b/src/lib/providers/jira/JiraApiClient.ts
@@ -0,0 +1,271 @@
+// JiraApiClient - REST API wrapper for Jira operations
+// Handles authentication and common API request patterns
+
+import https from 'node:https'
+import { getLogger } from '../../../utils/logger-context.js'
+import { markdownToAdf } from './AdfMarkdownConverter.js'
+
+/**
+ * Jira API configuration
+ */
+export interface JiraConfig {
+ host: string // e.g., "https://yourcompany.atlassian.net"
+ username: string // email address or username
+ apiToken: string // API token from Atlassian account
+}
+
+/**
+ * Jira issue response from API
+ */
+export interface JiraIssue {
+ id: string
+ key: string
+ fields: {
+ summary: string
+ description: string | null | unknown // Can be string, ADF object, or null
+ status: {
+ name: string
+ }
+ issuetype: {
+ name: string
+ }
+ project: {
+ key: string
+ name: string
+ }
+ assignee: {
+ displayName: string
+ emailAddress: string
+ accountId: string
+ } | null
+ reporter: {
+ displayName: string
+ emailAddress: string
+ accountId: string
+ }
+ labels: string[]
+ created: string
+ updated: string
+ [key: string]: unknown // Allow additional fields
+ }
+ [key: string]: unknown // Allow additional top-level fields
+}
+
+/**
+ * Jira comment response from API
+ */
+export interface JiraComment {
+ id: string
+ author: {
+ displayName: string
+ emailAddress: string
+ accountId: string
+ }
+ body: string | unknown // Can be string or ADF object
+ created: string
+ updated: string
+ [key: string]: unknown
+}
+
+/**
+ * Jira transition response from API
+ */
+export interface JiraTransition {
+ id: string
+ name: string
+ to: {
+ id: string
+ name: string
+ }
+}
+
+/**
+ * JiraApiClient provides low-level REST API access to Jira
+ *
+ * Authentication: Basic Auth with username and API token
+ * API Reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
+ */
+export class JiraApiClient {
+ private readonly baseUrl: string
+ private readonly authHeader: string
+
+ constructor(config: JiraConfig) {
+ this.baseUrl = `${config.host.replace(/\/$/, '')}/rest/api/3`
+
+ // Create Basic Auth header
+ const credentials = Buffer.from(`${config.username}:${config.apiToken}`).toString('base64')
+ this.authHeader = `Basic ${credentials}`
+ }
+
+ /**
+ * Make an HTTP request to Jira API
+ */
+ private async request(
+ method: 'GET' | 'POST' | 'PUT',
+ endpoint: string,
+ body?: unknown
+ ): Promise {
+ const url = new URL(`${this.baseUrl}${endpoint}`)
+ getLogger().debug(`Jira API ${method} request`, { url: url.toString() })
+
+ return new Promise((resolve, reject) => {
+ const options: https.RequestOptions = {
+ hostname: url.hostname,
+ port: url.port || 443,
+ path: url.pathname + url.search,
+ method,
+ headers: {
+ 'Authorization': this.authHeader,
+ 'Accept': 'application/json',
+ 'Content-Type': 'application/json',
+ },
+ }
+
+ const req = https.request(options, (res) => {
+ let data = ''
+
+ res.on('data', (chunk) => {
+ data += chunk
+ })
+
+ res.on('end', () => {
+ if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+ reject(new Error(`Jira API error (${res.statusCode}): ${data}`))
+ return
+ }
+
+ // Handle empty response (e.g., 204 No Content)
+ if (res.statusCode === 204 || !data) {
+ resolve({} as T)
+ return
+ }
+
+ try {
+ resolve(JSON.parse(data) as T)
+ } catch (error) {
+ reject(new Error(`Failed to parse Jira API response: ${error}`))
+ }
+ })
+ })
+
+ req.on('error', (error) => {
+ reject(new Error(`Jira API request failed: ${error.message}`))
+ })
+
+ if (body) {
+ req.write(JSON.stringify(body))
+ }
+
+ req.end()
+ })
+ }
+
+ /**
+ * Make a GET request to Jira API
+ */
+ private async get(endpoint: string): Promise {
+ return this.request('GET', endpoint)
+ }
+
+ /**
+ * Make a POST request to Jira API
+ */
+ private async post(endpoint: string, body: unknown): Promise {
+ return this.request('POST', endpoint, body)
+ }
+
+ /**
+ * Make a PUT request to Jira API
+ */
+ private async put(endpoint: string, body: unknown): Promise {
+ return this.request('PUT', endpoint, body)
+ }
+
+ /**
+ * Fetch an issue by key (e.g., "PROJ-123")
+ */
+ async getIssue(issueKey: string): Promise {
+ return this.get(`/issue/${issueKey}`)
+ }
+
+ /**
+ * Add a comment to an issue
+ * Accepts Markdown content which is converted to ADF for Jira
+ */
+ async addComment(issueKey: string, body: string): Promise {
+ const adfBody = markdownToAdf(body);
+ getLogger().debug('Adding comment to Jira issue', { issueKey, body, adfBody })
+ return this.post(`/issue/${issueKey}/comment`, {
+ body: adfBody
+ })
+ }
+
+ /**
+ * Get all comments for an issue
+ */
+ async getComments(issueKey: string): Promise {
+ const response = await this.get<{ comments: JiraComment[] }>(`/issue/${issueKey}/comment`)
+ return response.comments
+ }
+
+ /**
+ * Update a comment on an issue
+ * Accepts Markdown content which is converted to ADF for Jira
+ */
+ async updateComment(issueKey: string, commentId: string, body: string): Promise {
+ return this.put(`/issue/${issueKey}/comment/${commentId}`, {
+ body: markdownToAdf(body),
+ })
+ }
+
+ /**
+ * Get available transitions for an issue
+ */
+ async getTransitions(issueKey: string): Promise {
+ const response = await this.get<{ transitions: JiraTransition[] }>(`/issue/${issueKey}/transitions`)
+ return response.transitions
+ }
+
+ /**
+ * Transition an issue to a new state
+ */
+ async transitionIssue(issueKey: string, transitionId: string): Promise {
+ await this.post(`/issue/${issueKey}/transitions`, {
+ transition: {
+ id: transitionId,
+ },
+ })
+ }
+
+ /**
+ * Create a new issue
+ * Accepts Markdown description which is converted to ADF for Jira
+ */
+ async createIssue(projectKey: string, summary: string, description: string, issueType = 'Task'): Promise {
+ return this.post('/issue', {
+ fields: {
+ project: {
+ key: projectKey,
+ },
+ summary,
+ description: markdownToAdf(description),
+ issuetype: {
+ name: issueType,
+ },
+ },
+ })
+ }
+
+ /**
+ * Test connection to Jira API
+ */
+ async testConnection(): Promise {
+ try {
+ await this.get('/myself')
+ return true
+ } catch (error) {
+ getLogger().error('Jira connection test failed', { error })
+ return false
+ }
+ }
+}
diff --git a/src/lib/providers/jira/JiraIssueTracker.ts b/src/lib/providers/jira/JiraIssueTracker.ts
new file mode 100644
index 00000000..b0bb441d
--- /dev/null
+++ b/src/lib/providers/jira/JiraIssueTracker.ts
@@ -0,0 +1,347 @@
+// JiraIssueTracker - Implements IssueTracker interface for Jira
+// Provides issue management operations via Jira REST API
+
+import type { IssueTracker } from '../../IssueTracker.js'
+import type { Issue, IssueTrackerInputDetection } from '../../../types/index.js'
+import { JiraApiClient, type JiraConfig, type JiraIssue, type JiraTransition } from './JiraApiClient.js'
+import { getLogger } from '../../../utils/logger-context.js'
+import { adfToMarkdown } from './AdfMarkdownConverter.js'
+
+/**
+ * Jira-specific configuration
+ */
+export interface JiraTrackerConfig extends JiraConfig {
+ projectKey: string
+ transitionMappings?: Record // Map iloom states to Jira transition names
+}
+
+/**
+ * JiraIssueTracker implements IssueTracker for Jira
+ *
+ * Key differences from GitHub/Linear:
+ * - Issue identifiers are strings (e.g., "PROJ-123")
+ * - No issue prefix (unlike GitHub's "#")
+ * - State changes require workflow transitions (not direct status updates)
+ * - Content uses Atlassian Document Format (ADF), converted to/from Markdown
+ */
+export class JiraIssueTracker implements IssueTracker {
+ readonly providerName = 'jira'
+ readonly supportsPullRequests = false
+
+ private readonly client: JiraApiClient
+ private readonly config: JiraTrackerConfig
+
+ constructor(config: JiraTrackerConfig) {
+ this.config = config
+ this.client = new JiraApiClient({
+ host: config.host,
+ username: config.username,
+ apiToken: config.apiToken,
+ })
+ }
+
+ /**
+ * Normalize identifier to canonical uppercase form
+ * Jira issue keys are case-sensitive in the API (must be uppercase)
+ */
+ normalizeIdentifier(identifier: string | number): string {
+ return String(identifier).toUpperCase()
+ }
+
+ /**
+ * Detect input type from user input
+ * Jira issues follow pattern: PROJECTKEY-123 (case-insensitive)
+ */
+ async detectInputType(input: string): Promise {
+ // Pattern: PROJECTKEY-123 (case-insensitive to accept lowercase from branch names or user input)
+ const jiraPattern = /^([A-Z][A-Z0-9]+)-(\d+)$/i
+ const match = input.match(jiraPattern)
+
+ if (!match) {
+ return { type: 'unknown', identifier: null, rawInput: input }
+ }
+
+ const issueKey = this.normalizeIdentifier(input)
+ getLogger().debug('Checking if input is a Jira issue', { issueKey })
+
+ // Verify the issue exists
+ try {
+ await this.client.getIssue(issueKey)
+ return { type: 'issue', identifier: issueKey, rawInput: input }
+ } catch (error) {
+ getLogger().debug('Issue not found', { issueKey, error })
+ return { type: 'unknown', identifier: null, rawInput: input }
+ }
+ }
+
+ /**
+ * Fetch issue details
+ */
+ async fetchIssue(identifier: string | number): Promise {
+ const issueKey = this.normalizeIdentifier(identifier)
+ getLogger().debug('Fetching Jira issue', { issueKey })
+
+ const jiraIssue = await this.client.getIssue(issueKey)
+ return this.mapJiraIssueToIssue(jiraIssue)
+ }
+
+ /**
+ * Check if issue exists (silent validation)
+ */
+ async isValidIssue(identifier: string | number): Promise {
+ try {
+ return await this.fetchIssue(identifier)
+ } catch (error) {
+ getLogger().debug('Issue validation failed', { identifier, error })
+ return false
+ }
+ }
+
+ /**
+ * Validate issue state
+ * Note: Jira doesn't have a simple "closed" state - depends on workflow
+ */
+ async validateIssueState(issue: Issue): Promise {
+ // Jira state validation is workflow-specific
+ // For now, we'll just log the state
+ getLogger().debug('Jira issue state', { issueKey: issue.number, state: issue.state })
+
+ // Could add custom validation logic here based on config
+ // For example, warn if issue is in "Done" state
+ if (issue.state.toLowerCase() === 'done') {
+ getLogger().warn('Issue is already in Done state', { issueKey: issue.number })
+ }
+ }
+
+ /**
+ * Create a new issue
+ */
+ async createIssue(
+ title: string,
+ body: string,
+ _repository?: string,
+ _labels?: string[]
+ ): Promise<{ number: string | number; url: string }> {
+ getLogger().debug('Creating Jira issue', { title, projectKey: this.config.projectKey })
+
+ // Convert markdown body to plain text for Jira description
+ // Note: Jira API expects Atlassian Document Format (ADF)
+ // We use a simplified plain text approach here
+ const jiraIssue = await this.client.createIssue(
+ this.config.projectKey,
+ title,
+ body
+ )
+
+ return {
+ number: jiraIssue.key,
+ url: `${this.config.host}/browse/${jiraIssue.key}`,
+ }
+ }
+
+ /**
+ * Get issue URL
+ */
+ async getIssueUrl(identifier: string | number): Promise {
+ const issueKey = this.normalizeIdentifier(identifier)
+ return `${this.config.host}/browse/${issueKey}`
+ }
+
+ /**
+ * Move issue to "In Progress" state
+ * Uses configured transition mapping or default transition name
+ */
+ async moveIssueToInProgress(identifier: string | number): Promise {
+ const issueKey = this.normalizeIdentifier(identifier)
+ getLogger().debug('Moving Jira issue to In Progress', { issueKey })
+
+ // Get available transitions
+ const transitions = await this.client.getTransitions(issueKey)
+
+ // Look for the transition in config mapping or use default names
+ const transitionName = this.config.transitionMappings?.['In Progress']
+ ?? this.findTransitionByName(transitions, ['In Progress', 'Start Progress', 'Start'])
+
+ if (!transitionName) {
+ throw new Error(
+ `Could not find "In Progress" transition for ${issueKey}. ` +
+ `Available transitions: ${transitions.map(t => t.name).join(', ')}. ` +
+ `Configure custom mapping in settings.json: issueManagement.jira.transitionMappings`
+ )
+ }
+
+ // Find transition ID
+ const transition = transitions.find(t => t.name === transitionName)
+ if (!transition) {
+ throw new Error(`Transition "${transitionName}" not found`)
+ }
+
+ await this.client.transitionIssue(issueKey, transition.id)
+ getLogger().info('Issue transitioned successfully', { issueKey, transition: transitionName })
+ }
+
+ /**
+ * Move issue to "Ready for Review" state
+ * Uses configured transition mapping or default transition name
+ */
+ async moveIssueToReadyForReview(identifier: string | number): Promise {
+ const issueKey = this.normalizeIdentifier(identifier)
+ getLogger().debug('Moving Jira issue to Ready for Review', { issueKey })
+
+ // Get available transitions
+ const transitions = await this.client.getTransitions(issueKey)
+
+ // Look for the transition in config mapping or use default names
+ const transitionName = this.config.transitionMappings?.['Ready for Review']
+ ?? this.findTransitionByName(transitions, ['Ready for Review', 'In Review', 'Code Review', 'Review'])
+
+ if (!transitionName) {
+ throw new Error(
+ `Could not find "Ready for Review" transition for ${issueKey}. ` +
+ `Available transitions: ${transitions.map(t => t.name).join(', ')}. ` +
+ `Configure custom mapping in settings.json: issueManagement.jira.transitionMappings`
+ )
+ }
+
+ // Find transition ID
+ const transition = transitions.find(t => t.name === transitionName)
+ if (!transition) {
+ throw new Error(`Transition "${transitionName}" not found`)
+ }
+
+ await this.client.transitionIssue(issueKey, transition.id)
+ getLogger().info('Issue transitioned to Ready for Review', { issueKey, transition: transitionName })
+ }
+
+ /**
+ * Extract context from issue for AI prompts
+ */
+ extractContext(entity: Issue): string {
+ return `Issue: ${entity.number}
+Title: ${entity.title}
+Status: ${entity.state}
+URL: ${entity.url}
+
+Description:
+${entity.body}
+
+${entity.labels.length > 0 ? `Labels: ${entity.labels.join(', ')}` : ''}
+${entity.assignees.length > 0 ? `Assignees: ${entity.assignees.join(', ')}` : ''}`
+ }
+
+ /**
+ * Get issue details (alias for fetchIssue for MCP compatibility)
+ */
+ async getIssue(identifier: string | number): Promise {
+ return this.fetchIssue(identifier)
+ }
+
+ /**
+ * Get all comments for an issue
+ */
+ async getComments(identifier: string | number): Promise> {
+ const issueKey = this.normalizeIdentifier(identifier)
+ getLogger().debug('Fetching Jira comments', { issueKey })
+
+ const comments = await this.client.getComments(issueKey)
+
+ // Map to expected format
+ return comments.map(comment => ({
+ id: comment.id,
+ body: adfToMarkdown(comment.body),
+ author: comment.author,
+ createdAt: comment.created,
+ updatedAt: comment.updated,
+ }))
+ }
+
+ /**
+ * Add a comment to an issue
+ */
+ async addComment(identifier: string | number, body: string): Promise<{ id: string }> {
+ const issueKey = this.normalizeIdentifier(identifier)
+ getLogger().debug('Adding Jira comment', { issueKey })
+
+ const comment = await this.client.addComment(issueKey, body)
+ return { id: comment.id }
+ }
+
+ /**
+ * Update an existing comment
+ */
+ async updateComment(identifier: string | number, commentId: string, body: string): Promise {
+ const issueKey = this.normalizeIdentifier(identifier)
+ getLogger().debug('Updating Jira comment', { issueKey, commentId })
+
+ await this.client.updateComment(issueKey, commentId, body)
+ }
+
+ /**
+ * Get configuration (for MCP provider)
+ */
+ getConfig(): JiraTrackerConfig {
+ return this.config
+ }
+
+ /**
+ * Map Jira API issue to generic Issue type
+ */
+ private mapJiraIssueToIssue(jiraIssue: JiraIssue): Issue & {
+ id?: string
+ key?: string
+ author?: {
+ displayName: string
+ emailAddress: string
+ accountId: string
+ }
+ assignee?: {
+ displayName: string
+ emailAddress: string
+ accountId: string
+ } | null
+ issueType?: string
+ status?: string
+ } {
+ // Extract description - handle ADF format or plain string
+ const description = adfToMarkdown(jiraIssue.fields.description)
+
+ return {
+ id: jiraIssue.id,
+ key: jiraIssue.key,
+ number: jiraIssue.key,
+ title: jiraIssue.fields.summary,
+ body: description,
+ state: jiraIssue.fields.status.name.toLowerCase() as 'open' | 'closed',
+ labels: jiraIssue.fields.labels,
+ assignees: jiraIssue.fields.assignee
+ ? [jiraIssue.fields.assignee.displayName]
+ : [],
+ assignee: jiraIssue.fields.assignee,
+ author: jiraIssue.fields.reporter,
+ url: `${this.config.host}/browse/${jiraIssue.key}`,
+ issueType: jiraIssue.fields.issuetype.name,
+ status: jiraIssue.fields.status.name,
+ }
+ }
+
+ /**
+ * Find a transition by name, trying multiple possible names
+ */
+ private findTransitionByName(transitions: JiraTransition[], names: string[]): string | null {
+ for (const name of names) {
+ const transition = transitions.find(t =>
+ t.name.toLowerCase() === name.toLowerCase()
+ )
+ if (transition) {
+ return transition.name
+ }
+ }
+ return null
+ }
+}
diff --git a/src/lib/providers/jira/index.ts b/src/lib/providers/jira/index.ts
new file mode 100644
index 00000000..d6f1ae13
--- /dev/null
+++ b/src/lib/providers/jira/index.ts
@@ -0,0 +1,4 @@
+// Jira provider exports
+export { JiraApiClient, type JiraConfig, type JiraIssue, type JiraComment, type JiraTransition } from './JiraApiClient.js'
+export { JiraIssueTracker, type JiraTrackerConfig } from './JiraIssueTracker.js'
+export { adfToMarkdown, markdownToAdf } from './AdfMarkdownConverter.js'
diff --git a/src/mcp/IssueManagementProviderFactory.ts b/src/mcp/IssueManagementProviderFactory.ts
index 384d171b..794d2a6e 100644
--- a/src/mcp/IssueManagementProviderFactory.ts
+++ b/src/mcp/IssueManagementProviderFactory.ts
@@ -5,6 +5,8 @@
import type { IssueManagementProvider, IssueProvider } from './types.js'
import { GitHubIssueManagementProvider } from './GitHubIssueManagementProvider.js'
import { LinearIssueManagementProvider } from './LinearIssueManagementProvider.js'
+import { JiraIssueManagementProvider } from './JiraIssueManagementProvider.js'
+import type { IloomSettings } from '../lib/SettingsManager.js'
/**
* Factory class for creating issue management providers
@@ -12,13 +14,20 @@ import { LinearIssueManagementProvider } from './LinearIssueManagementProvider.j
export class IssueManagementProviderFactory {
/**
* Create an issue management provider based on the provider type
+ * @param provider - The provider type (github, linear, jira)
+ * @param settings - Required for Jira provider, optional for others
*/
- static create(provider: IssueProvider): IssueManagementProvider {
+ static create(provider: IssueProvider, settings?: IloomSettings): IssueManagementProvider {
switch (provider) {
case 'github':
return new GitHubIssueManagementProvider()
case 'linear':
return new LinearIssueManagementProvider()
+ case 'jira':
+ if (!settings) {
+ throw new Error('Settings required for Jira provider')
+ }
+ return new JiraIssueManagementProvider(settings)
default:
throw new Error(`Unsupported issue management provider: ${provider}`)
}
diff --git a/src/mcp/JiraIssueManagementProvider.ts b/src/mcp/JiraIssueManagementProvider.ts
new file mode 100644
index 00000000..d1605af9
--- /dev/null
+++ b/src/mcp/JiraIssueManagementProvider.ts
@@ -0,0 +1,257 @@
+/**
+ * Jira implementation of Issue Management Provider
+ * Uses JiraIssueTracker for all operations
+ * Normalizes Jira-specific fields to provider-agnostic core fields
+ */
+
+import type {
+ IssueManagementProvider,
+ GetIssueInput,
+ GetCommentInput,
+ CreateCommentInput,
+ UpdateCommentInput,
+ CreateIssueInput,
+ CreateIssueResult,
+ IssueResult,
+ CommentDetailResult,
+ CommentResult,
+ FlexibleAuthor,
+} from './types.js'
+import { JiraIssueTracker } from '../lib/providers/jira/JiraIssueTracker.js'
+import type { JiraTrackerConfig } from '../lib/providers/jira/JiraIssueTracker.js'
+import type { Issue } from '../types/index.js'
+import { SettingsManager } from '../lib/SettingsManager.js'
+import type { IloomSettings } from '../lib/SettingsManager.js'
+
+/**
+ * Normalize Jira author to FlexibleAuthor format
+ */
+function normalizeAuthor(author: { displayName?: string; emailAddress?: string; accountId?: string } | null | undefined): FlexibleAuthor | null {
+ if (!author) return null
+
+ return {
+ id: author.accountId ?? author.emailAddress ?? 'unknown',
+ displayName: author.displayName ?? author.emailAddress ?? 'Unknown',
+ ...(author.emailAddress && { email: author.emailAddress }),
+ ...(author.accountId && { accountId: author.accountId }),
+ }
+}
+/**
+ * Extract Jira configuration from settings (for cli usage) or environment variables (in mcp server)
+ */
+const getJiraTrackerConfig = (settings: IloomSettings): JiraTrackerConfig => {
+ const jiraSettings = settings.issueManagement?.jira
+
+ if (jiraSettings?.host && jiraSettings?.username && jiraSettings?.apiToken && jiraSettings?.projectKey) {
+ const config: JiraTrackerConfig = {
+ host: jiraSettings.host,
+ username: jiraSettings.username,
+ apiToken: jiraSettings.apiToken,
+ projectKey: jiraSettings.projectKey,
+ }
+
+ if (jiraSettings.transitionMappings) {
+ config.transitionMappings = jiraSettings.transitionMappings
+ }
+
+ return config;
+ }
+
+ if (process.env.JIRA_HOST && process.env.JIRA_USERNAME && process.env.JIRA_API_TOKEN && process.env.JIRA_PROJECT_KEY) {
+ const config: JiraTrackerConfig = {
+ host: process.env.JIRA_HOST,
+ username: process.env.JIRA_USERNAME,
+ apiToken: process.env.JIRA_API_TOKEN,
+ projectKey: process.env.JIRA_PROJECT_KEY,
+ }
+
+ if (process.env.JIRA_TRANSITION_MAPPINGS) {
+ try {
+ config.transitionMappings = JSON.parse(process.env.JIRA_TRANSITION_MAPPINGS)
+ } catch {
+ throw new Error('Invalid JSON in JIRA_TRANSITION_MAPPINGS environment variable')
+ }
+ }
+
+ return config
+ }
+
+ throw new Error(
+ 'Missing required Jira settings: issueManagement.jira.{host, username, apiToken, projectKey} or corresponding environment variables'
+ )
+}
+
+/**
+ * Jira-specific implementation of IssueManagementProvider
+ */
+export class JiraIssueManagementProvider implements IssueManagementProvider {
+ readonly providerName = 'jira'
+ readonly issuePrefix = ''
+ private tracker: JiraIssueTracker
+
+ constructor(settings: IloomSettings) {
+ const config = getJiraTrackerConfig(settings);
+
+ this.tracker = new JiraIssueTracker(config)
+ }
+
+ /**
+ * Static factory for convenience when settings aren't pre-loaded
+ */
+ static async create(): Promise {
+ const settingsManager = new SettingsManager()
+ const settings = await settingsManager.loadSettings()
+ return new JiraIssueManagementProvider(settings)
+ }
+
+ /**
+ * Fetch issue details using JiraIssueTracker
+ */
+ async getIssue(input: GetIssueInput): Promise {
+ const { number, includeComments = true } = input
+
+ // Fetch issue from Jira
+ const issue = await this.tracker.getIssue(number)
+ const issueExt = issue as Issue & {
+ id?: string
+ key?: string
+ author?: {
+ displayName?: string
+ emailAddress?: string
+ accountId?: string
+ }
+ issueType?: string
+ priority?: string
+ status?: string
+ }
+
+ // Normalize to IssueResult format
+ const result: IssueResult = {
+ id: issueExt.id ?? String(issue.number),
+ title: issue.title,
+ body: issue.body,
+ state: issue.state,
+ url: issue.url,
+ provider: 'jira',
+ author: normalizeAuthor(issueExt.author),
+ number: issue.number,
+ key: issueExt.key,
+ // Preserve Jira-specific fields
+ ...(issueExt.issueType && { issueType: issueExt.issueType }),
+ ...(issueExt.priority && { priority: issueExt.priority }),
+ ...(issueExt.status && { status: issueExt.status }),
+ }
+
+ // Add labels if present
+ if (issue.labels && issue.labels.length > 0) {
+ result.labels = issue.labels.map(label => ({ name: label }))
+ }
+
+ // Add assignees if present - Issue type uses assignees array of strings
+ if (issue.assignees && issue.assignees.length > 0) {
+ result.assignees = issue.assignees.map(name => ({
+ id: name,
+ displayName: name,
+ }))
+ }
+
+ // Fetch and add comments if requested
+ if (includeComments) {
+ const comments = await this.tracker.getComments(number)
+ result.comments = comments.map((comment: {
+ id: string
+ body: string
+ author: { displayName: string; emailAddress: string; accountId: string }
+ createdAt: string
+ updatedAt: string
+ }) => ({
+ id: comment.id,
+ body: comment.body,
+ author: normalizeAuthor(comment.author),
+ createdAt: comment.createdAt,
+ updatedAt: comment.updatedAt,
+ }))
+ }
+
+ return result
+ }
+
+ /**
+ * Fetch a specific comment by ID
+ */
+ async getComment(input: GetCommentInput): Promise {
+ const { commentId, number } = input
+
+ // Fetch all comments and find the specific one
+ const comments = await this.tracker.getComments(number)
+ const comment = comments.find(c => c.id === commentId)
+
+ if (!comment) {
+ throw new Error(`Comment ${commentId} not found on issue ${number}`)
+ }
+
+ return {
+ id: comment.id,
+ body: comment.body,
+ author: normalizeAuthor(comment.author),
+ created_at: comment.createdAt,
+ updated_at: comment.updatedAt,
+ }
+ }
+
+ /**
+ * Create a new comment on an issue
+ */
+ async createComment(input: CreateCommentInput): Promise {
+ const { number, body } = input
+ const normalizedKey = this.tracker.normalizeIdentifier(number)
+
+ // Jira doesn't distinguish between issue and PR comments
+ const comment = await this.tracker.addComment(normalizedKey, body)
+
+ return {
+ id: comment.id,
+ url: `${this.tracker.getConfig().host}/browse/${normalizedKey}?focusedCommentId=${comment.id}`,
+ created_at: new Date().toISOString(),
+ }
+ }
+
+ /**
+ * Update an existing comment
+ */
+ async updateComment(input: UpdateCommentInput): Promise {
+ const { commentId, number, body } = input
+ const normalizedKey = this.tracker.normalizeIdentifier(number)
+
+ // Update comment via tracker
+ await this.tracker.updateComment(normalizedKey, commentId, body)
+
+ return {
+ id: commentId,
+ url: `${this.tracker.getConfig().host}/browse/${normalizedKey}?focusedCommentId=${commentId}`,
+ updated_at: new Date().toISOString(),
+ }
+ }
+
+ /**
+ * Create a new issue
+ */
+ async createIssue(input: CreateIssueInput): Promise {
+ const { title, body } = input
+
+ // Create issue via tracker (labels not supported in current implementation)
+ const issue = await this.tracker.createIssue(title, body)
+
+ const result: CreateIssueResult = {
+ id: String(issue.number),
+ url: issue.url,
+ }
+
+ // Only add number if it's actually a number
+ if (typeof issue.number === 'number') {
+ result.number = issue.number
+ }
+
+ return result
+ }
+}
diff --git a/src/mcp/issue-management-server.ts b/src/mcp/issue-management-server.ts
index 23a14ddd..e8556937 100644
--- a/src/mcp/issue-management-server.ts
+++ b/src/mcp/issue-management-server.ts
@@ -10,6 +10,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'
import { IssueManagementProviderFactory } from './IssueManagementProviderFactory.js'
+import { SettingsManager } from '../lib/SettingsManager.js'
+import type { IloomSettings } from '../lib/SettingsManager.js'
import type {
IssueProvider,
GetIssueInput,
@@ -19,6 +21,9 @@ import type {
CreateIssueInput,
} from './types.js'
+// Module-level settings loaded at startup
+let settings: IloomSettings | undefined
+
// Validate required environment variables
function validateEnvironment(): IssueProvider {
const provider = process.env.ISSUE_PROVIDER as IssueProvider | undefined
@@ -27,8 +32,8 @@ function validateEnvironment(): IssueProvider {
process.exit(1)
}
- if (provider !== 'github' && provider !== 'linear') {
- console.error(`Invalid ISSUE_PROVIDER: ${provider}. Must be 'github' or 'linear'`)
+ if (provider !== 'github' && provider !== 'linear' && provider !== 'jira') {
+ console.error(`Invalid ISSUE_PROVIDER: ${provider}. Must be 'github', 'linear', or 'jira'`)
process.exit(1)
}
@@ -53,6 +58,19 @@ function validateEnvironment(): IssueProvider {
}
}
+ // Jira requires host, username, API token, and project key
+ if (provider === 'jira') {
+ const required = ['JIRA_HOST', 'JIRA_USERNAME', 'JIRA_API_TOKEN', 'JIRA_PROJECT_KEY']
+ const missing = required.filter((key) => !process.env[key])
+
+ if (missing.length > 0) {
+ console.error(
+ `Missing required environment variables for Jira provider: ${missing.join(', ')}`
+ )
+ process.exit(1)
+ }
+ }
+
return provider
}
@@ -91,7 +109,7 @@ server.registerTool(
body: z.string().describe('Issue body/description'),
state: z.string().describe('Issue state (open, closed, etc.)'),
url: z.string().describe('Issue URL'),
- provider: z.enum(['github', 'linear']).describe('Issue management provider'),
+ provider: z.enum(['github', 'linear', 'jira']).describe('Issue management provider'),
// Flexible author - core fields + passthrough
author: flexibleAuthorSchema.nullable().describe(
@@ -122,7 +140,8 @@ server.registerTool(
try {
const provider = IssueManagementProviderFactory.create(
- process.env.ISSUE_PROVIDER as IssueProvider
+ process.env.ISSUE_PROVIDER as IssueProvider,
+ settings
)
const result = await provider.getIssue({ number, includeComments })
@@ -172,7 +191,8 @@ server.registerTool(
try {
const provider = IssueManagementProviderFactory.create(
- process.env.ISSUE_PROVIDER as IssueProvider
+ process.env.ISSUE_PROVIDER as IssueProvider,
+ settings
)
const result = await provider.getComment({ commentId, number })
@@ -221,7 +241,8 @@ server.registerTool(
try {
const provider = IssueManagementProviderFactory.create(
- process.env.ISSUE_PROVIDER as IssueProvider
+ process.env.ISSUE_PROVIDER as IssueProvider,
+ settings
)
const result = await provider.createComment({ number, body, type })
@@ -270,7 +291,8 @@ server.registerTool(
try {
const provider = IssueManagementProviderFactory.create(
- process.env.ISSUE_PROVIDER as IssueProvider
+ process.env.ISSUE_PROVIDER as IssueProvider,
+ settings
)
const result = await provider.updateComment({ commentId, number, body })
@@ -322,7 +344,8 @@ server.registerTool(
try {
const provider = IssueManagementProviderFactory.create(
- process.env.ISSUE_PROVIDER as IssueProvider
+ process.env.ISSUE_PROVIDER as IssueProvider,
+ settings
)
const result = await provider.createIssue({ title, body, labels, teamKey })
@@ -350,6 +373,11 @@ server.registerTool(
async function main(): Promise {
console.error('Starting Issue Management MCP Server...')
+ // Load settings for providers that need them
+ const settingsManager = new SettingsManager()
+ settings = await settingsManager.loadSettings()
+ console.error('Settings loaded')
+
// Validate environment and get provider
const provider = validateEnvironment()
console.error('Environment validated')
diff --git a/src/mcp/types.ts b/src/mcp/types.ts
index b8938c7b..73502d2e 100644
--- a/src/mcp/types.ts
+++ b/src/mcp/types.ts
@@ -5,7 +5,7 @@
/**
* Supported issue management providers
*/
-export type IssueProvider = 'github' | 'linear'
+export type IssueProvider = 'github' | 'linear' | 'jira'
/**
* Environment variables required by MCP server
diff --git a/src/types/index.ts b/src/types/index.ts
index 27d4ac50..8b3aad02 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -181,6 +181,7 @@ export interface FinishOptions {
noBrowser?: boolean // --no-browser - Skip opening PR in browser (github-pr mode only)
cleanup?: boolean // --cleanup / --no-cleanup - Control worktree cleanup after finishing
json?: boolean // --json - Output result as JSON
+ skipToPr?: boolean // --skip-to-pr - Skip rebase/validation/commit, go directly to PR creation (debug)
}
/**
@@ -331,6 +332,7 @@ export interface CommitOptions {
skipVerify?: boolean // Skip pre-commit hooks (--no-verify flag)
skipVerifySilent?: boolean // Skip without warning (for --wip-commit)
trailerType?: 'Refs' | 'Fixes' // Trailer type: "Refs" references issue, "Fixes" closes it (default: 'Fixes' for backward compat)
+ timeout?: number // Timeout in milliseconds for commit operation
}
/**
diff --git a/src/utils/claude.test.ts b/src/utils/claude.test.ts
index f2f678f0..c1efe788 100644
--- a/src/utils/claude.test.ts
+++ b/src/utils/claude.test.ts
@@ -334,7 +334,7 @@ describe('claude utils', () => {
expect(execa).toHaveBeenCalledWith(
'claude',
- ['-p', '--output-format', 'stream-json', '--verbose', '--add-dir', '/tmp'],
+ ['-p', '--output-format', 'stream-json', '--verbose', '--add-dir', '/tmp', '--debug'],
expect.objectContaining({
input: prompt,
timeout: 0,
diff --git a/src/utils/claude.ts b/src/utils/claude.ts
index a06b0681..25b2e025 100644
--- a/src/utils/claude.ts
+++ b/src/utils/claude.ts
@@ -191,11 +191,15 @@ export async function launchClaude(
if (sessionId) {
args.push('--session-id', sessionId)
}
+ const isDebugMode = logger.isDebugEnabled()
+
+ if (isDebugMode) {
+ args.push('--debug') // Enable debug mode for more detailed logs
+ }
try {
if (headless) {
// Headless mode: capture and return output
- const isDebugMode = logger.isDebugEnabled()
// Set up execa options based on debug mode
const execaOptions = {
diff --git a/src/utils/git.ts b/src/utils/git.ts
index 76c78c57..5ed7ba86 100644
--- a/src/utils/git.ts
+++ b/src/utils/git.ts
@@ -26,12 +26,12 @@ export class GitCommandError extends Error {
*/
export async function executeGitCommand(
args: string[],
- options?: { cwd?: string; timeout?: number; stdio?: 'inherit' | 'pipe'; env?: NodeJS.ProcessEnv }
+ options?: { cwd?: string; timeout?: number | undefined; stdio?: 'inherit' | 'pipe'; env?: NodeJS.ProcessEnv }
): Promise {
try {
const result = await execa('git', args, {
cwd: options?.cwd ?? process.cwd(),
- timeout: options?.timeout ?? 30000,
+ timeout: options?.timeout ?? 60000,
encoding: 'utf8',
stdio: options?.stdio ?? 'pipe',
verbose: logger.isDebugEnabled(),
diff --git a/src/utils/mcp.ts b/src/utils/mcp.ts
index 72084725..0930a8d9 100644
--- a/src/utils/mcp.ts
+++ b/src/utils/mcp.ts
@@ -18,7 +18,7 @@ import type { LoomMetadata } from '../lib/MetadataManager.js'
export async function generateIssueManagementMcpConfig(
contextType?: 'issue' | 'pr',
repo?: string,
- provider: 'github' | 'linear' = 'github',
+ provider: 'github' | 'linear' | 'jira' = 'github',
settings?: IloomSettings,
draftPrNumber?: number
): Promise[]> {
@@ -74,7 +74,7 @@ export async function generateIssueManagementMcpConfig(
githubEventName: githubEventName ?? 'auto-detect',
draftPrNumber: draftPrNumber ?? undefined,
})
- } else {
+ } else if (provider === 'linear') {
// Linear needs API token passed through
const apiToken = settings?.issueManagement?.linear?.apiToken ?? process.env.LINEAR_API_TOKEN
@@ -95,6 +95,32 @@ export async function generateIssueManagementMcpConfig(
hasTeamKey: !!teamKey,
contextType: contextType ?? 'auto-detect',
})
+ } else if (provider === 'jira') {
+ // Jira configuration - pass credentials via environment variables
+ const jiraSettings = settings?.issueManagement?.jira
+
+ if (jiraSettings?.host) {
+ envVars.JIRA_HOST = jiraSettings.host
+ }
+ if (jiraSettings?.username) {
+ envVars.JIRA_USERNAME = jiraSettings.username
+ }
+ if (jiraSettings?.apiToken) {
+ envVars.JIRA_API_TOKEN = jiraSettings.apiToken
+ }
+ if (jiraSettings?.projectKey) {
+ envVars.JIRA_PROJECT_KEY = jiraSettings.projectKey
+ }
+ if (jiraSettings?.transitionMappings) {
+ envVars.JIRA_TRANSITION_MAPPINGS = JSON.stringify(jiraSettings.transitionMappings)
+ }
+
+ logger.debug('Generated MCP config for Jira issue management', {
+ provider,
+ hasApiToken: !!jiraSettings?.apiToken,
+ projectKey: jiraSettings?.projectKey,
+ contextType: contextType ?? 'auto-detect',
+ })
}
// Generate single MCP server config
diff --git a/src/utils/remote.ts b/src/utils/remote.ts
index 9f4c2ac2..31c4a223 100644
--- a/src/utils/remote.ts
+++ b/src/utils/remote.ts
@@ -54,23 +54,35 @@ export async function parseGitRemotes(cwd?: string): Promise {
}
/**
- * Extract owner and repo from GitHub URL
- * Supports both HTTPS and SSH formats
+ * Extract owner and repo from Git remote URL
+ * Supports both HTTPS and SSH formats for GitHub and BitBucket
*/
function extractOwnerRepoFromUrl(url: string): { owner: string; repo: string } | null {
// Remove .git suffix if present
const cleanUrl = url.replace(/\.git$/, '')
- // HTTPS format: https://github.com/owner/repo
- const httpsMatch = cleanUrl.match(/https?:\/\/github\.com\/([^/]+)\/([^/]+)/)
- if (httpsMatch?.[1] && httpsMatch?.[2]) {
- return { owner: httpsMatch[1], repo: httpsMatch[2] }
+ // GitHub HTTPS format: https://github.com/owner/repo
+ const githubHttpsMatch = cleanUrl.match(/https?:\/\/github\.com\/([^/]+)\/([^/]+)/)
+ if (githubHttpsMatch?.[1] && githubHttpsMatch?.[2]) {
+ return { owner: githubHttpsMatch[1], repo: githubHttpsMatch[2] }
}
- // SSH format: git@github.com:owner/repo
- const sshMatch = cleanUrl.match(/git@github\.com:([^/]+)\/(.+)/)
- if (sshMatch?.[1] && sshMatch?.[2]) {
- return { owner: sshMatch[1], repo: sshMatch[2] }
+ // GitHub SSH format: git@github.com:owner/repo
+ const githubSshMatch = cleanUrl.match(/git@github\.com:([^/]+)\/(.+)/)
+ if (githubSshMatch?.[1] && githubSshMatch?.[2]) {
+ return { owner: githubSshMatch[1], repo: githubSshMatch[2] }
+ }
+
+ // BitBucket HTTPS format: https://bitbucket.org/workspace/repo
+ const bitbucketHttpsMatch = cleanUrl.match(/https?:\/\/bitbucket\.org\/([^/]+)\/([^/]+)/)
+ if (bitbucketHttpsMatch?.[1] && bitbucketHttpsMatch?.[2]) {
+ return { owner: bitbucketHttpsMatch[1], repo: bitbucketHttpsMatch[2] }
+ }
+
+ // BitBucket SSH format: git@bitbucket.org:workspace/repo
+ const bitbucketSshMatch = cleanUrl.match(/git@bitbucket\.org:([^/]+)\/(.+)/)
+ if (bitbucketSshMatch?.[1] && bitbucketSshMatch?.[2]) {
+ return { owner: bitbucketSshMatch[1], repo: bitbucketSshMatch[2] }
}
return null
diff --git a/templates/agents/iloom-issue-analyze-and-plan.md b/templates/agents/iloom-issue-analyze-and-plan.md
index a276bc28..ab06bffa 100644
--- a/templates/agents/iloom-issue-analyze-and-plan.md
+++ b/templates/agents/iloom-issue-analyze-and-plan.md
@@ -216,6 +216,20 @@ Based on the lightweight analysis, create a detailed plan following the project'
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/agents/iloom-issue-analyzer.md b/templates/agents/iloom-issue-analyzer.md
index 4bde6292..c119b47a 100644
--- a/templates/agents/iloom-issue-analyzer.md
+++ b/templates/agents/iloom-issue-analyzer.md
@@ -289,6 +289,20 @@ Use domain-specific MCP tools when available (Figma MCP, Database MCPs, etc.) as
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/agents/iloom-issue-complexity-evaluator.md b/templates/agents/iloom-issue-complexity-evaluator.md
index 4d27bd29..b052824a 100644
--- a/templates/agents/iloom-issue-complexity-evaluator.md
+++ b/templates/agents/iloom-issue-complexity-evaluator.md
@@ -170,6 +170,20 @@ Estimate the following metrics:
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/agents/iloom-issue-enhancer.md b/templates/agents/iloom-issue-enhancer.md
index 205a3149..5188aa35 100644
--- a/templates/agents/iloom-issue-enhancer.md
+++ b/templates/agents/iloom-issue-enhancer.md
@@ -94,6 +94,20 @@ Before asking questions, perform minimal research to avoid questions whose answe
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/agents/iloom-issue-implementer.md b/templates/agents/iloom-issue-implementer.md
index 60b0b539..de22d340 100644
--- a/templates/agents/iloom-issue-implementer.md
+++ b/templates/agents/iloom-issue-implementer.md
@@ -18,6 +18,20 @@ This enables the recap panel to show quick-reference links to artifacts created
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/agents/iloom-issue-planner.md b/templates/agents/iloom-issue-planner.md
index 33089dd8..ba53527c 100644
--- a/templates/agents/iloom-issue-planner.md
+++ b/templates/agents/iloom-issue-planner.md
@@ -34,6 +34,20 @@ Your primary task is to:
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/agents/iloom-issue-reviewer.md b/templates/agents/iloom-issue-reviewer.md
index 13554515..a5331191 100644
--- a/templates/agents/iloom-issue-reviewer.md
+++ b/templates/agents/iloom-issue-reviewer.md
@@ -46,6 +46,20 @@ This enables the recap panel to show quick-reference links to artifacts created
IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
Available Tools:
- mcp__issue_management__get_issue: Fetch issue details
Parameters: { number: string, includeComments?: boolean }
diff --git a/templates/prompts/session-summary-prompt.txt b/templates/prompts/session-summary-prompt.txt
index 61a5fbd5..5213d12b 100644
--- a/templates/prompts/session-summary-prompt.txt
+++ b/templates/prompts/session-summary-prompt.txt
@@ -89,6 +89,20 @@ The reader doesn't care about your internal process. They care about:
- Any explanation of what you're doing
- Any text after the closing ` ` tag
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
**Output ONLY the markdown content below, starting with `## iloom Session Summary` and ending with `