jira-ai 1.2.0 → 1.3.0

package/README.md

@@ -19,33 +19,6 @@ An AI-friendly CLI for Jira that prioritizes efficiency and security.
 npm install -g jira-ai
 ```
 
-### Install in Claude code: 
-#### Step 1: Add the Marketplace
-Add this marketplace to your Claude instance:
-```bash
-claude plugin marketplace add festoinc/management-plugins
-```
-
-#### Step 2: Install the Plugin
-```bash
-claude plugin install jira-ai-connector@management-plugins
-```
-
-Will be avalibale automatically as skill
-
-
-### Install in  Gemini CLI
-#### Step 1: Add the Extension
-Add this extension to your Gemini CLI:
-```bash
-gemini extension install https://github.com/festoinc/management-plugins
-```
-
-Will be avalible as slash command 
-```bash
-/work-with-jira
-```
-
 ## Quick Start
 
 Authenticate with credentials (non-interactive — JSON or .env file only):
@@ -76,6 +49,40 @@ Errors are returned as structured JSON to stdout:
 { "error": true, "message": "Issue not found", "hints": ["Check the issue key"], "exitCode": 1 }
 ```
 
+### Issue Hierarchy Tree
+
+Explore issue hierarchies with the `issue tree` command. It returns a directed graph (nodes + edges) representing the full parent-child hierarchy starting from a given issue:
+
+```bash
+jira-ai issue tree PROJ-10
+```
+
+Include linked issues as leaf nodes:
+
+```bash
+jira-ai issue tree PROJ-10 --links
+```
+
+Filter linked issues by type and limit depth:
+
+```bash
+jira-ai issue tree PROJ-10 --links --types "Blocks,Relates" --depth 2 --max-nodes 100
+```
+
+### Sprint Hierarchy Tree
+
+View all issues in a sprint organized by their hierarchy (epics → stories → subtasks):
+
+```bash
+jira-ai sprint tree 42
+```
+
+Customize traversal depth and node limit:
+
+```bash
+jira-ai sprint tree 42 --depth 4 --max-nodes 500
+```
+
 ### Rich Issue Management
 
 Create issues with detailed field support:

package/dist/cli.js

@@ -20,6 +20,8 @@ import { listLinkTypesCommand } from './commands/list-link-types.js';
 import { createTaskCommand } from './commands/create-task.js';
 import { transitionCommand, listTransitionsCommand } from './commands/transition.js';
 import { issueAssignCommand } from './commands/issue.js';
+import { issueTreeCommand } from './commands/issue-tree.js';
+import { sprintTreeCommand } from './commands/sprint-tree.js';
 import { uploadAttachmentCommand, listAttachmentsCommand, downloadAttachmentCommand, deleteAttachmentCommand, } from './commands/attach.js';
 import { getIssueStatisticsCommand } from './commands/get-issue-statistics.js';
 import { getPersonWorklogCommand } from './commands/get-person-worklog.js';
@@ -328,6 +330,19 @@ issueAttach
 }, {
     validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
 }));
+issue
+    .command('tree <issue-key>')
+    .description('Show the full issue hierarchy tree rooted at an issue, including subtasks and optionally linked issues.')
+    .option('--links', 'Include linked issues as single-hop leaf nodes')
+    .option('--depth <number>', 'Max traversal depth (default: 3)', '3')
+    .option('--max-nodes <number>', 'Max nodes in tree (default: 200)', '200')
+    .option('--types <types>', 'Comma-separated link types to include (e.g. Blocks,Relates)')
+    .action(withPermission('issue.tree', (issueKey, options) => issueTreeCommand(issueKey, {
+    links: options.links || false,
+    depth: options.depth ? Number(options.depth) : undefined,
+    maxNodes: options.maxNodes ? Number(options.maxNodes) : undefined,
+    types: options.types,
+}), { validateArgs: (args) => validateOptions(IssueKeySchema, args[0]) }));
 // =============================================================================
 // PROJECT COMMANDS
 // =============================================================================
@@ -595,6 +610,15 @@ sprint
     .option('--before <key>', 'Rank before this issue')
     .option('--after <key>', 'Rank after this issue')
     .action(withPermission('sprint.move', (sprintId, options) => sprintMoveCommand(Number(sprintId), options), { schema: SprintMoveSchema }));
+sprint
+    .command('tree <sprint-id>')
+    .description('Show the full issue hierarchy tree for a sprint, grouped by epics.')
+    .option('--depth <number>', 'Max traversal depth (default: 3)', '3')
+    .option('--max-nodes <number>', 'Max nodes in tree (default: 200)', '200')
+    .action(withPermission('sprint.tree', (sprintId, options) => sprintTreeCommand(sprintId, {
+    depth: options.depth ? Number(options.depth) : undefined,
+    maxNodes: options.maxNodes ? Number(options.maxNodes) : undefined,
+})));
 // =============================================================================
 // BACKLOG COMMANDS
 // =============================================================================

package/dist/commands/issue-tree.js

@@ -0,0 +1,6 @@
+import { buildIssueTree } from '../lib/tree-builder.js';
+import { outputResult } from '../lib/json-mode.js';
+export async function issueTreeCommand(issueKey, options) {
+    const result = await buildIssueTree(issueKey, options);
+    outputResult(result);
+}

package/dist/commands/sprint-tree.js

@@ -0,0 +1,6 @@
+import { buildSprintTree } from '../lib/tree-builder.js';
+import { outputResult } from '../lib/json-mode.js';
+export async function sprintTreeCommand(sprintId, options) {
+    const result = await buildSprintTree(sprintId, options);
+    outputResult(result);
+}

package/dist/lib/jira-client.js

@@ -249,13 +249,14 @@ export async function getProjectStatuses(projectIdOrKey) {
 /**
  * Search for issues using JQL query
  */
-export async function searchIssuesByJql(jqlQuery, maxResults) {
+export async function searchIssuesByJql(jqlQuery, maxResults, extraFields) {
     const client = getJiraClient();
     const filteredJql = applyGlobalFilters(jqlQuery);
+    const fields = ['summary', 'status', 'assignee', 'priority', ...(extraFields ?? [])];
     const response = await client.issueSearch.searchForIssuesUsingJqlEnhancedSearch({
         jql: filteredJql,
         maxResults,
-        fields: ['summary', 'status', 'assignee', 'priority'],
+        fields,
     });
     return response.issues?.map((issue) => ({
         key: issue.key || '',
@@ -269,6 +270,12 @@ export async function searchIssuesByJql(jqlQuery, maxResults) {
         priority: issue.fields?.priority ? {
             name: issue.fields.priority.name || 'Unknown',
         } : null,
+        issuetype: issue.fields?.issuetype ? {
+            name: issue.fields.issuetype.name || 'Unknown',
+        } : undefined,
+        parent: issue.fields?.parent ? {
+            key: issue.fields.parent.key || '',
+        } : undefined,
     })) || [];
 }
 /**
@@ -904,7 +911,7 @@ export async function getIssueLinks(issueIdOrKey) {
     const client = await getJiraClient();
     const issue = await client.issues.getIssue({
         issueIdOrKey,
-        fields: ['issuelinks'],
+        fields: ['issuelinks', 'issuetype'],
     });
     const raw = issue.fields?.issuelinks ?? [];
     return raw.map((link) => ({
@@ -921,6 +928,9 @@ export async function getIssueLinks(issueIdOrKey) {
                 key: link.inwardIssue.key,
                 summary: link.inwardIssue.fields?.summary ?? '',
                 status: { name: link.inwardIssue.fields?.status?.name ?? '' },
+                issuetype: link.inwardIssue.fields?.issuetype
+                    ? { name: link.inwardIssue.fields.issuetype.name ?? 'Unknown' }
+                    : undefined,
             }
             : undefined,
         outwardIssue: link.outwardIssue
@@ -929,6 +939,9 @@ export async function getIssueLinks(issueIdOrKey) {
                 key: link.outwardIssue.key,
                 summary: link.outwardIssue.fields?.summary ?? '',
                 status: { name: link.outwardIssue.fields?.status?.name ?? '' },
+                issuetype: link.outwardIssue.fields?.issuetype
+                    ? { name: link.outwardIssue.fields.issuetype.name ?? 'Unknown' }
+                    : undefined,
             }
             : undefined,
     }));

package/dist/lib/tree-builder.js

@@ -0,0 +1,233 @@
+import { getTaskWithDetails, searchIssuesByJql, getIssueLinks } from './jira-client.js';
+import { getSprintIssues } from './agile-client.js';
+import { applyGlobalFilters } from './settings.js';
+export async function buildIssueTree(issueKey, options) {
+    const { depth = 3, maxNodes = 200, links = false, types } = options;
+    const nodes = [];
+    const edges = [];
+    const visited = new Set();
+    let truncated = false;
+    // Fetch root issue
+    const root = await getTaskWithDetails(issueKey);
+    // Add parent (epic/ancestor) if exists — derived from root.parent, no extra API call needed
+    if (root.parent) {
+        const parentKey = root.parent.key;
+        if (!visited.has(parentKey)) {
+            visited.add(parentKey);
+            nodes.push({
+                key: parentKey,
+                summary: root.parent.summary || '',
+                status: root.parent.status?.name || 'Unknown',
+                type: 'Epic',
+                priority: null,
+                assignee: null,
+            });
+            edges.push({ from: parentKey, to: root.key, relation: 'hierarchy' });
+        }
+    }
+    // Add root node
+    if (!visited.has(root.key)) {
+        if (nodes.length < maxNodes) {
+            visited.add(root.key);
+            nodes.push({
+                key: root.key,
+                summary: root.summary,
+                status: root.status.name,
+                type: root.type || 'Unknown',
+                priority: root.priority || null,
+                assignee: root.assignee?.displayName || null,
+            });
+        }
+        else {
+            truncated = true;
+            return { root: issueKey, nodes, edges, depth: 0, truncated: true, totalNodes: nodes.length };
+        }
+    }
+    // BFS traversal using batched JQL: parent in (key1, key2, ...)
+    let currentLevel = [root.key];
+    let currentDepth = 0;
+    while (currentLevel.length > 0 && currentDepth < depth) {
+        if (nodes.length >= maxNodes) {
+            truncated = true;
+            break;
+        }
+        const jql = applyGlobalFilters(`parent in (${currentLevel.join(',')})`);
+        const children = await searchIssuesByJql(jql, 1000, ['issuetype', 'parent']);
+        const nextLevel = [];
+        for (const child of children) {
+            if (visited.has(child.key))
+                continue;
+            if (nodes.length >= maxNodes) {
+                truncated = true;
+                break;
+            }
+            visited.add(child.key);
+            nodes.push({
+                key: child.key,
+                summary: child.summary,
+                status: child.status.name,
+                type: child.issuetype?.name || 'Unknown',
+                priority: child.priority?.name || null,
+                assignee: child.assignee?.displayName || null,
+            });
+            // Determine parent for edge: when there's one parent in currentLevel all children map to it
+            let parentKey;
+            if (currentLevel.length === 1) {
+                parentKey = currentLevel[0];
+            }
+            else {
+                parentKey = child.parent?.key;
+            }
+            if (parentKey) {
+                edges.push({
+                    from: parentKey,
+                    to: child.key,
+                    relation: child.issuetype?.name === 'Sub-task' ? 'subtask' : 'hierarchy',
+                });
+            }
+            nextLevel.push(child.key);
+        }
+        if (truncated)
+            break;
+        currentLevel = nextLevel;
+        currentDepth++;
+    }
+    // Add linked issues as single-hop leaf nodes when --links is true
+    if (links) {
+        const issueLinks = await getIssueLinks(issueKey);
+        const allowedTypes = types ? types.split(',').map((t) => t.trim()) : null;
+        await Promise.all(issueLinks.map(async (link) => {
+            const linkedIssue = link.outwardIssue || link.inwardIssue;
+            if (!linkedIssue)
+                return;
+            const linkType = link.type.name;
+            if (allowedTypes && !allowedTypes.includes(linkType))
+                return;
+            if (visited.has(linkedIssue.key))
+                return;
+            if (nodes.length >= maxNodes) {
+                truncated = true;
+                return;
+            }
+            visited.add(linkedIssue.key);
+            nodes.push({
+                key: linkedIssue.key,
+                summary: linkedIssue.summary || '',
+                status: linkedIssue.status?.name || 'Unknown',
+                type: linkedIssue.issuetype?.name || 'Unknown',
+                priority: null,
+                assignee: null,
+            });
+            edges.push({ from: issueKey, to: linkedIssue.key, relation: linkType });
+        }));
+    }
+    return {
+        root: issueKey,
+        nodes,
+        edges,
+        depth: currentDepth,
+        truncated,
+        totalNodes: nodes.length,
+    };
+}
+export async function buildSprintTree(sprintId, options) {
+    const { depth = 3, maxNodes = 200 } = options;
+    const nodes = [];
+    const edges = [];
+    let truncated = false;
+    // Virtual sprint root node
+    const sprintRootKey = `sprint-${sprintId}`;
+    nodes.push({
+        key: sprintRootKey,
+        summary: `Sprint ${sprintId}`,
+        status: 'active',
+        type: 'sprint',
+        priority: null,
+        assignee: null,
+    });
+    // Fetch all sprint issues
+    const { issues } = await getSprintIssues(Number(sprintId));
+    if (issues.length === 0) {
+        return { root: sprintRootKey, nodes, edges, depth: 0, truncated: false, totalNodes: 1 };
+    }
+    // Build lookup map
+    const issueMap = new Map();
+    for (const issue of issues) {
+        issueMap.set(issue.key, issue);
+    }
+    const visited = new Set([sprintRootKey]);
+    let maxDepth = 0;
+    // Build parent-to-children index once to avoid O(n^2) inner loop in BFS
+    const parentToChildren = new Map();
+    for (const issue of issues) {
+        const parentKey = issue.fields.parent?.key;
+        if (parentKey && issueMap.has(parentKey)) {
+            const siblings = parentToChildren.get(parentKey) ?? [];
+            siblings.push(issue.key);
+            parentToChildren.set(parentKey, siblings);
+        }
+    }
+    // Seed BFS with top-level issues: those whose parent is absent or outside the sprint
+    let queue = [];
+    for (const issue of issues) {
+        const parentKey = issue.fields.parent?.key;
+        if (!parentKey || !issueMap.has(parentKey)) {
+            queue.push({ key: issue.key, d: 1 });
+        }
+    }
+    while (queue.length > 0) {
+        const next = [];
+        for (const { key, d } of queue) {
+            if (visited.has(key))
+                continue;
+            if (d > depth)
+                continue;
+            if (nodes.length >= maxNodes + 1) {
+                // maxNodes + 1 because sprint root is not counted against maxNodes
+                truncated = true;
+                break;
+            }
+            const issue = issueMap.get(key);
+            if (!issue)
+                continue;
+            visited.add(key);
+            const fields = issue.fields;
+            nodes.push({
+                key: issue.key,
+                summary: fields.summary || '',
+                status: fields.status?.name || 'Unknown',
+                type: fields.issuetype?.name || 'Unknown',
+                priority: fields.priority?.name || null,
+                assignee: fields.assignee?.displayName || null,
+            });
+            // Edge: connect to parent if it's in the visited set, otherwise to sprint root
+            const parentKey = fields.parent?.key;
+            if (parentKey && visited.has(parentKey)) {
+                edges.push({ from: parentKey, to: key, relation: 'hierarchy' });
+            }
+            else {
+                edges.push({ from: sprintRootKey, to: key, relation: 'hierarchy' });
+            }
+            if (d > maxDepth)
+                maxDepth = d;
+            // Enqueue children using the pre-built index
+            const childKeys = parentToChildren.get(key) ?? [];
+            for (const childKey of childKeys) {
+                if (!visited.has(childKey)) {
+                    next.push({ key: childKey, d: d + 1 });
+                }
+            }
+        }
+        if (truncated)
+            break;
+        queue = next;
+    }
+    return {
+        root: sprintRootKey,
+        nodes,
+        edges,
+        depth: maxDepth,
+        truncated,
+        totalNodes: nodes.length,
+    };
+}

package/dist/lib/tree-types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jira-ai",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI friendly Jira CLI to save context",
   "type": "module",
   "main": "dist/cli.js",