jira-ai 1.1.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:
@@ -191,6 +198,43 @@ When `authType` is set to `service_account`, jira-ai automatically:
 
 Existing configurations using standard API tokens are unaffected.
 
+## Saved Queries
+
+Define reusable JQL queries in your `settings.yaml` under the `saved-queries` key to avoid repeating common searches.
+
+### Configuration
+
+Add a `saved-queries` map to your `settings.yaml` — each key is a query name (lowercase alphanumeric with hyphens) and each value is a JQL string:
+
+```yaml
+saved-queries:
+  my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"
+  overdue-tasks: "project = PROJ AND duedate < now() AND status != Done"
+  my-assignee: "assignee = currentUser()"
+```
+
+### Usage
+
+Run a saved query by name:
+
+```bash
+jira-ai issue search --query my-open-bugs
+```
+
+List all configured saved queries:
+
+```bash
+jira-ai issue search --list-queries
+```
+
+Combine with result limits:
+
+```bash
+jira-ai issue search --query overdue-tasks --limit 10
+```
+
+Saved queries are mutually exclusive with raw JQL — you cannot provide both a positional JQL argument and `--query` at the same time.
+
 ## Configuration & Restrictions
 
 Tool allows you to have very complex configutations of what Projects/Jira commands/Issue types you would have acess to thought the tool.

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';
@@ -131,14 +133,20 @@ issue
     .option('--custom-field <field=value>', 'Custom field in fieldId=value format (repeatable)', (val, prev) => [...(prev || []), val], [])
     .action(withPermission('issue.create', createTaskCommand, { schema: CreateTaskSchema }));
 issue
-    .command('search <jql-query>')
-    .description('Execute a JQL search query. Returns issues with key, summary, status, assignee, and priority.')
+    .command('search [jql-query]')
+    .description('Execute a JQL search query. Provide raw JQL or use --query to reference a saved query.')
     .option('-l, --limit <number>', 'Maximum number of results (default: 50)', '50')
+    .option('--query <name>', 'Use a saved query by name (mutually exclusive with positional JQL)')
+    .option('--list-queries', 'List all available saved queries')
     .action(withPermission('issue.search', runJqlCommand, {
     schema: RunJqlSchema,
     validateArgs: (args) => {
-        if (typeof args[0] !== 'string' || args[0].trim() === '') {
-            throw new CliError('JQL query cannot be empty');
+        const jqlQuery = args[0];
+        const opts = args[args.length - 2];
+        const hasQuery = opts && opts.query;
+        const hasListQueries = opts && opts.listQueries;
+        if (!hasQuery && !hasListQueries && (typeof jqlQuery !== 'string' || jqlQuery.trim() === '')) {
+            throw new CliError('JQL query cannot be empty. Provide a JQL query, use --query <name>, or use --list-queries.');
         }
     }
 }));
@@ -322,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
 // =============================================================================
@@ -589,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/run-jql.js

@@ -1,11 +1,35 @@
 import { searchIssuesByJql } from '../lib/jira-client.js';
 import { outputResult } from '../lib/json-mode.js';
+import { getSavedQuery, listSavedQueries } from '../lib/settings.js';
+import { CliError } from '../types/errors.js';
 export async function runJqlCommand(jqlQuery, options) {
-    // Parse and validate limit parameter
+    // Handle --list-queries
+    if (options.listQueries) {
+        const queries = listSavedQueries();
+        outputResult({ queries });
+        return;
+    }
+    // Mutual exclusion: can't have both positional JQL and --query
+    if (jqlQuery && jqlQuery.trim() !== '' && options.query) {
+        throw new CliError('Cannot specify both JQL query and --query. Use one or the other.');
+    }
+    let resolvedJql;
+    if (options.query) {
+        const savedJql = getSavedQuery(options.query);
+        if (savedJql === undefined) {
+            const available = listSavedQueries().map((q) => q.name).join(', ');
+            const availableMsg = available ? available : '(none)';
+            throw new CliError(`Saved query '${options.query}' not found. Available: ${availableMsg}`);
+        }
+        resolvedJql = savedJql;
+    }
+    else {
+        resolvedJql = jqlQuery;
+    }
     let maxResults = options.limit || 50;
     if (maxResults > 1000) {
         maxResults = 1000;
     }
-    const issues = await searchIssuesByJql(jqlQuery, maxResults);
+    const issues = await searchIssuesByJql(resolvedJql, maxResults);
     outputResult(issues);
 }

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/settings.js

@@ -4,6 +4,16 @@ import os from 'os';
 import yaml from 'js-yaml';
 import { CliError } from '../types/errors.js';
 import { SettingsSchema } from './validation.js';
+export function getSavedQuery(name) {
+    const settings = loadSettings();
+    return settings.savedQueries?.[name];
+}
+export function listSavedQueries() {
+    const settings = loadSettings();
+    if (!settings.savedQueries)
+        return [];
+    return Object.entries(settings.savedQueries).map(([name, jql]) => ({ name, jql }));
+}
 // Mapping from old flat command names to new hierarchical paths
 export const LEGACY_COMMAND_MAP = {
     'me': 'user.me',

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/dist/lib/validation.js

@@ -113,6 +113,8 @@ export const UpdateDescriptionSchema = z.object({
 });
 export const RunJqlSchema = z.object({
     limit: NumericStringSchema.optional(),
+    query: z.string().optional(),
+    listQueries: z.boolean().optional(),
 });
 export const TimeframeSchema = z.string().regex(/^\d+d$/, 'Timeframe must be in format like "7d" or "30d"');
 export const GetPersonWorklogSchema = z.object({
@@ -157,10 +159,12 @@ export const OrganizationSettingsSchema = z.object({
     'allowed-commands': z.array(z.string()).nullish().transform(val => val || DEFAULT_ALLOWED_COMMANDS),
     'allowed-confluence-spaces': z.array(z.string()).nullish().transform(val => val || ['all']),
 });
+export const SavedQueryNameSchema = z.string().regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/, 'Query name must be lowercase alphanumeric with hyphens (e.g., "my-query"), cannot start or end with a hyphen');
 export const SettingsSchema = z.object({
     defaults: OrganizationSettingsSchema.optional(),
     projects: z.array(ProjectSettingSchema).optional(),
     commands: z.array(z.string()).optional(),
+    savedQueries: z.record(SavedQueryNameSchema, z.string().min(1)).optional(),
 });
 // =============================================================================
 // EPIC VALIDATION SCHEMAS

package/package.json

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

package/settings.yaml

@@ -14,3 +14,12 @@ commands:
   - run-jql
   - list-issue-types
   - project-statuses
+
+# Saved Queries: Define reusable JQL queries by name.
+# Keys must be lowercase alphanumeric with optional hyphens (e.g., "my-query").
+# Values are JQL query strings. Saved queries are used with:
+#   jira-ai issue search --query <name>
+#   jira-ai issue search --list-queries
+# saved-queries:
+#   my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"
+#   overdue-tasks: "project = PROJ AND duedate < now() AND status != Done"