jira-ai 1.2.0 → 1.4.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';
@@ -46,6 +48,7 @@ program
     .description('CLI tool for interacting with Atlassian Jira')
     .version(getVersion())
     .option('--compact', 'Output as compact JSON')
+    .option('--dry-run', 'Preview changes without executing them')
     .addHelpText('after', () => {
     const latestVersion = checkForUpdateSync();
     if (latestVersion) {
@@ -328,6 +331,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 +611,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/create-task.js

@@ -6,6 +6,7 @@ import { CommandError } from '../lib/errors.js';
 import { validateOptions, CreateTaskSchema } from '../lib/validation.js';
 import { isCommandAllowed, isProjectAllowed } from '../lib/settings.js';
 import { outputResult } from '../lib/json-mode.js';
+import { isDryRun, formatDryRunResult } from '../lib/dry-run.js';
 export async function createTaskCommand(options) {
     validateOptions(CreateTaskSchema, options);
     const { title, project, issueType, parent, priority, description, descriptionFile, labels, component, fixVersion, dueDate, assignee, customField } = options;
@@ -74,6 +75,17 @@ export async function createTaskCommand(options) {
             issueFields[fieldId] = isNaN(numValue) ? rawValue : numValue;
         }
     }
+    if (isDryRun()) {
+        const changes = {
+            project,
+            summary: title,
+            issueType,
+            ...(parent !== undefined ? { parent } : {}),
+            ...issueFields,
+        };
+        formatDryRunResult('issue.create', project, changes);
+        return;
+    }
     try {
         const result = await createIssue({
             project,

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/commands/transition.js

@@ -5,13 +5,14 @@ import { outputResult } from '../lib/json-mode.js';
 import { markdownToAdf } from 'marklassian';
 import { FieldResolver } from '../lib/field-resolver.js';
 import { processMentionsInADF } from '../lib/adf-mentions.js';
+import { isDryRun, formatDryRunResult } from '../lib/dry-run.js';
 export async function transitionCommand(taskId, toStatus, options) {
     // Validate mutual exclusivity of --comment and --comment-file
     if (options?.comment && options?.commentFile) {
         throw new CommandError('Cannot use both --comment and --comment-file flags simultaneously.');
     }
     // Check permissions and filters
-    await validateIssuePermissions(taskId, 'transition');
+    const currentIssue = await validateIssuePermissions(taskId, 'transition');
     try {
         const transitions = await getIssueTransitions(taskId);
         const matchingTransitions = transitions.filter((t) => t.to.name.toLowerCase() === toStatus.toLowerCase());
@@ -34,6 +35,35 @@ export async function transitionCommand(taskId, toStatus, options) {
             });
         }
         const transition = matchingTransitions[0];
+        if (isDryRun()) {
+            const changes = {
+                status: {
+                    from: currentIssue?.status?.name,
+                    to: transition.to.name,
+                },
+            };
+            if (options?.resolution !== undefined) {
+                changes.resolution = { to: options.resolution };
+            }
+            if (options?.assignee !== undefined) {
+                changes.assignee = { to: options.assignee };
+            }
+            if (options?.fixVersion !== undefined) {
+                changes.fixVersions = { to: options.fixVersion };
+            }
+            if (options?.customFields && options.customFields.length > 0) {
+                for (const entry of options.customFields) {
+                    const eqIdx = entry.indexOf('=');
+                    if (eqIdx === -1)
+                        continue;
+                    const fieldId = entry.slice(0, eqIdx).trim();
+                    const value = entry.slice(eqIdx + 1).trim();
+                    changes[fieldId] = { to: value };
+                }
+            }
+            formatDryRunResult('issue.transition', taskId, changes);
+            return;
+        }
         // Build optional payload if any options were provided
         let payload;
         if (options && Object.keys(options).some(k => options[k] !== undefined)) {

package/dist/commands/update-issue.js

@@ -6,6 +6,7 @@ import { CommandError } from '../lib/errors.js';
 import { validateOptions, UpdateIssueSchema, IssueKeySchema } from '../lib/validation.js';
 import { isCommandAllowed, isProjectAllowed } from '../lib/settings.js';
 import { outputResult } from '../lib/json-mode.js';
+import { isDryRun, formatDryRunResult } from '../lib/dry-run.js';
 export async function updateIssueCommand(issueKey, options) {
     validateOptions(IssueKeySchema, issueKey);
     validateOptions(UpdateIssueSchema, options);
@@ -16,7 +17,47 @@ export async function updateIssueCommand(issueKey, options) {
     if (!isCommandAllowed('update-issue', projectKey)) {
         throw new CommandError(`Command 'update-issue' is not allowed for project ${projectKey}.`);
     }
-    await validateIssuePermissions(issueKey, 'update-issue');
+    const currentIssue = await validateIssuePermissions(issueKey, 'update-issue');
+    if (isDryRun()) {
+        const changes = {};
+        if (options.priority !== undefined) {
+            changes.priority = { from: currentIssue?.priority, to: options.priority };
+        }
+        if (options.summary !== undefined) {
+            changes.summary = { from: currentIssue?.summary, to: options.summary };
+        }
+        if (options.labels !== undefined || options.clearLabels) {
+            const newLabels = options.clearLabels ? [] : options.labels?.split(',').map(l => l.trim()).filter(Boolean);
+            changes.labels = { from: currentIssue?.labels, to: newLabels };
+        }
+        if (options.component !== undefined) {
+            changes.components = { from: currentIssue?.components, to: options.component };
+        }
+        if (options.fixVersion !== undefined) {
+            changes.fixVersions = { from: currentIssue?.fixVersions, to: options.fixVersion };
+        }
+        if (options.dueDate !== undefined) {
+            changes.dueDate = { from: currentIssue?.duedate, to: options.dueDate };
+        }
+        if (options.assignee !== undefined) {
+            changes.assignee = { from: currentIssue?.assignee?.displayName, to: options.assignee };
+        }
+        if (options.description !== undefined || options.fromFile !== undefined) {
+            changes.description = { from: '(current)', to: '(updated)' };
+        }
+        if (options.customField && options.customField.length > 0) {
+            for (const cf of options.customField) {
+                const eqIdx = cf.indexOf('=');
+                if (eqIdx === -1)
+                    continue;
+                const fieldId = cf.slice(0, eqIdx);
+                const value = cf.slice(eqIdx + 1);
+                changes[fieldId] = { to: value };
+            }
+        }
+        formatDryRunResult('issue.update', issueKey, changes);
+        return;
+    }
     const fields = {};
     if (options.priority !== undefined) {
         if (!options.priority)

package/dist/lib/dry-run.js

@@ -0,0 +1,15 @@
+import { outputResult } from './json-mode.js';
+export function isDryRun() {
+    return process.argv.includes('--dry-run');
+}
+export function formatDryRunResult(command, target, changes, preview = {}) {
+    const result = {
+        dryRun: true,
+        command,
+        target,
+        changes,
+        preview,
+        message: 'No changes were made. Remove --dry-run to execute.',
+    };
+    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.4.0",
   "description": "AI friendly Jira CLI to save context",
   "type": "module",
   "main": "dist/cli.js",