jira-ai 1.4.0 → 1.5.0

package/README.md

@@ -49,6 +49,33 @@ Errors are returned as structured JSON to stdout:
 { "error": true, "message": "Issue not found", "hints": ["Check the issue key"], "exitCode": 1 }
 ```
 
+### Dry-Run / Preview Mode
+
+Preview write operations without executing them. The `--dry-run` flag is available on `issue create`, `issue update`, and `issue transition`. No Jira API write calls are made — output is purely a preview.
+
+```bash
+jira-ai issue update PROJ-123 --priority High --dry-run
+jira-ai issue transition PROJ-123 Done --resolution Fixed --dry-run
+jira-ai issue create --project PROJ --type Bug --title "Fix crash" --dry-run
+```
+
+Dry-run output follows a consistent JSON structure:
+
+```json
+{
+  "dryRun": true,
+  "command": "issue.update",
+  "target": "PROJ-123",
+  "changes": {
+    "priority": { "from": "Medium", "to": "High" }
+  },
+  "preview": { "...": "same output as the real command" },
+  "message": "No changes were made. Remove --dry-run to execute."
+}
+```
+
+The `preview` field contains the same output the real command would produce, so AI agents can process it identically. Phase 1 supports `issue create`, `issue update`, and `issue transition` only.
+
 ### 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:
@@ -147,6 +174,40 @@ jira-ai issue transitions PROJ-123
 
 When a transition fails due to missing required fields, the error message lists what is needed and suggests running `issue transitions <key>` to discover them.
 
+### Activity Feed & Comments
+
+View a unified activity feed combining changelog entries and comments for an issue:
+
+```bash
+jira-ai issue activity PROJ-123
+```
+
+Filter by time, activity type, or author:
+
+```bash
+jira-ai issue activity PROJ-123 --since 2026-01-01T00:00:00Z --types status_change,comment_added --author "Jane Smith"
+```
+
+Use `--compact` to strip comment bodies for maximum token efficiency:
+
+```bash
+jira-ai issue activity PROJ-123 --compact
+```
+
+List comments on an issue:
+
+```bash
+jira-ai issue comments PROJ-123
+```
+
+Use `--reverse` for chronological (oldest-first) order, or `--since` to filter by time:
+
+```bash
+jira-ai issue comments PROJ-123 --since 2026-01-01T00:00:00Z --reverse --limit 20
+```
+
+**Activity types:** `status_change`, `field_change`, `comment_added`, `comment_updated`, `attachment_added`, `attachment_removed`, `link_added`, `link_removed`
+
 ## Service Account Authentication
 
 Atlassian service accounts use scoped API tokens that must authenticate through the `api.atlassian.com` gateway rather than direct site URLs.

package/dist/cli.js

@@ -31,6 +31,8 @@ import { epicListCommand, epicGetCommand, epicCreateCommand, epicUpdateCommand,
 import { boardListCommand, boardGetCommand, boardConfigCommand, boardIssuesCommand, boardRankCommand, } from './commands/board.js';
 import { sprintListCommand, sprintGetCommand, sprintCreateCommand, sprintStartCommand, sprintCompleteCommand, sprintUpdateCommand, sprintDeleteCommand, sprintIssuesCommand, sprintMoveCommand, } from './commands/sprint.js';
 import { backlogMoveCommand } from './commands/backlog.js';
+import { issueCommentsCommand } from './commands/issue-comments.js';
+import { issueActivityCommand } from './commands/issue-activity.js';
 import { aboutCommand } from './commands/about.js';
 import { authCommand } from './commands/auth.js';
 import { settingsCommand } from './commands/settings.js';
@@ -208,6 +210,41 @@ issue
     schema: UpdateDescriptionSchema,
     validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
 }));
+issue
+    .command('comments <issue-id>')
+    .description('List comments on a Jira issue.')
+    .option('--limit <n>', 'Maximum number of comments to return (default: 50)')
+    .option('--since <iso>', 'Only include comments created on or after this ISO timestamp')
+    .option('--reverse', 'Return comments in chronological order (oldest first)')
+    .action(withPermission('issue.comments', (issueKey, options) => {
+    return issueCommentsCommand({
+        issueKey,
+        limit: options.limit ? parseInt(options.limit, 10) : undefined,
+        since: options.since,
+        reverse: options.reverse,
+    });
+}, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+issue
+    .command('activity <issue-id>')
+    .description('Show a unified activity feed (changelog + comments) for a Jira issue.')
+    .option('--since <iso>', 'Only include activities on or after this ISO timestamp')
+    .option('--limit <n>', 'Maximum number of activities to return (default: 50)')
+    .option('--types <types>', 'Comma-separated activity types to include (e.g., status_change,comment_added)')
+    .option('--author <name-or-email>', 'Filter by author display name, email, or accountId')
+    .action(withPermission('issue.activity', (issueKey, options) => {
+    return issueActivityCommand({
+        issueKey,
+        since: options.since,
+        limit: options.limit ? parseInt(options.limit, 10) : undefined,
+        types: options.types,
+        author: options.author,
+        compact: program.opts().compact || options.compact,
+    });
+}, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
 issue
     .command('stats <issue-ids>')
     .description('Calculate time-based metrics for one or more issues (comma-separated). Shows time logged, estimates, and status breakdown.')

package/dist/commands/issue-activity.js

@@ -0,0 +1,38 @@
+import { getIssueActivityFeed } from '../lib/jira-client.js';
+import { CommandError } from '../lib/errors.js';
+import { outputResult } from '../lib/json-mode.js';
+export async function issueActivityCommand(options) {
+    const { issueKey, since, limit, types, author, compact } = options;
+    if (since !== undefined && isNaN(new Date(since).getTime())) {
+        throw new CommandError('--since must be a valid ISO 8601 datetime (e.g. 2024-01-01T00:00:00Z)');
+    }
+    if (limit !== undefined && (limit < 1 || !Number.isInteger(limit))) {
+        throw new CommandError('--limit must be a positive integer (>= 1)');
+    }
+    try {
+        const result = await getIssueActivityFeed(issueKey, { since, limit, types, author });
+        if (compact) {
+            const compactResult = {
+                ...result,
+                activities: result.activities.map(({ commentBody: _omit, ...rest }) => rest),
+            };
+            outputResult(compactResult);
+        }
+        else {
+            outputResult(result);
+        }
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMsg = error.message?.toLowerCase() || '';
+        const hints = [];
+        if (errorMsg.includes('404')) {
+            hints.push('Check that the issue key is correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to view activity on this issue');
+        }
+        throw new CommandError(`Failed to get activity feed: ${error.message}`, { hints });
+    }
+}

package/dist/commands/issue-comments.js

@@ -0,0 +1,29 @@
+import { getIssueCommentsList } from '../lib/jira-client.js';
+import { CommandError } from '../lib/errors.js';
+import { outputResult } from '../lib/json-mode.js';
+export async function issueCommentsCommand(options) {
+    const { issueKey, limit, since, reverse } = options;
+    if (since !== undefined && isNaN(new Date(since).getTime())) {
+        throw new CommandError('--since must be a valid ISO 8601 datetime (e.g. 2024-01-01T00:00:00Z)');
+    }
+    if (limit !== undefined && (limit < 1 || !Number.isInteger(limit))) {
+        throw new CommandError('--limit must be a positive integer (>= 1)');
+    }
+    try {
+        const result = await getIssueCommentsList(issueKey, { limit, since, reverse });
+        outputResult(result);
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMsg = error.message?.toLowerCase() || '';
+        const hints = [];
+        if (errorMsg.includes('404')) {
+            hints.push('Check that the issue key is correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to view comments on this issue');
+        }
+        throw new CommandError(`Failed to get comments: ${error.message}`, { hints });
+    }
+}

package/dist/lib/jira-client.js

@@ -1044,6 +1044,183 @@ export async function downloadAttachment(issueKey, attachmentId, outputPath) {
     fs.writeFileSync(destPath, Buffer.from(content));
     return destPath;
 }
+/**
+ * Get comments for a Jira issue with pagination, since-filter, and ordering
+ */
+export async function getIssueCommentsList(issueKey, options = {}) {
+    const client = getJiraClient();
+    const { limit = 50, since, reverse = false } = options;
+    const maxResults = 100;
+    let startAt = 0;
+    let allComments = [];
+    let total = 0;
+    // Paginate through all comments
+    while (true) {
+        const response = await client.issueComments.getComments({
+            issueIdOrKey: issueKey,
+            maxResults,
+            startAt,
+            orderBy: 'created',
+        });
+        total = response.total ?? 0;
+        const pageComments = (response.comments || []).map((c) => ({
+            id: c.id || '',
+            author: {
+                accountId: c.author?.accountId || '',
+                displayName: c.author?.displayName || 'Unknown',
+                emailAddress: c.author?.emailAddress,
+            },
+            body: convertADFToMarkdown(c.body) || '',
+            created: c.created || '',
+            updated: c.updated || '',
+        }));
+        allComments = allComments.concat(pageComments);
+        if (allComments.length >= total || pageComments.length < maxResults) {
+            break;
+        }
+        startAt += maxResults;
+    }
+    // Apply --since filter
+    if (since) {
+        const sinceDate = new Date(since).getTime();
+        allComments = allComments.filter(c => new Date(c.created).getTime() >= sinceDate);
+    }
+    // Apply --reverse (ascending order; default is newest first)
+    if (!reverse) {
+        allComments = allComments.reverse();
+    }
+    // Apply --limit
+    const hasMore = allComments.length > limit;
+    const comments = allComments.slice(0, limit);
+    return {
+        issueKey,
+        comments,
+        total,
+        hasMore,
+    };
+}
+/**
+ * Get unified activity feed (changelog + comments) for a Jira issue
+ */
+export async function getIssueActivityFeed(issueKey, options = {}) {
+    const client = getJiraClient();
+    const { since, limit = 50, types, author } = options;
+    const sinceDate = since ? new Date(since).getTime() : null;
+    const typeFilter = types ? new Set(types.split(',').map(t => t.trim())) : null;
+    // --- Fetch all changelog entries with pagination ---
+    let changelogStartAt = 0;
+    const changelogMaxResults = 100;
+    let allChangelog = [];
+    while (true) {
+        const response = await client.issues.getChangeLogs({
+            issueIdOrKey: issueKey,
+            maxResults: changelogMaxResults,
+            startAt: changelogStartAt,
+        });
+        const values = response.values || [];
+        allChangelog = allChangelog.concat(values);
+        const responseTotal = response.total ?? 0;
+        if (allChangelog.length >= responseTotal || values.length < changelogMaxResults) {
+            break;
+        }
+        changelogStartAt += changelogMaxResults;
+    }
+    // --- Fetch all comments with pagination ---
+    let commentStartAt = 0;
+    const commentMaxResults = 100;
+    let allApiComments = [];
+    while (true) {
+        const response = await client.issueComments.getComments({
+            issueIdOrKey: issueKey,
+            maxResults: commentMaxResults,
+            startAt: commentStartAt,
+        });
+        const comments = response.comments || [];
+        allApiComments = allApiComments.concat(comments);
+        const responseTotal = response.total ?? 0;
+        if (allApiComments.length >= responseTotal || comments.length < commentMaxResults) {
+            break;
+        }
+        commentStartAt += commentMaxResults;
+    }
+    // --- Convert changelog to ActivityEntry list ---
+    const changelogActivities = [];
+    for (const history of allChangelog) {
+        const historyAuthor = {
+            accountId: history.author?.accountId || '',
+            displayName: history.author?.displayName || 'Unknown',
+            emailAddress: history.author?.emailAddress,
+        };
+        for (const item of history.items || []) {
+            const field = item.field || '';
+            const fieldLower = field.toLowerCase();
+            let type;
+            if (fieldLower === 'status') {
+                type = 'status_change';
+            }
+            else if (fieldLower.startsWith('link') || fieldLower === 'issuelinks') {
+                // Determine add vs remove from to/from strings
+                type = item.to ? 'link_added' : 'link_removed';
+            }
+            else if (fieldLower === 'attachment') {
+                type = item.to ? 'attachment_added' : 'attachment_removed';
+            }
+            else {
+                type = 'field_change';
+            }
+            changelogActivities.push({
+                id: `${history.id}-${field}`,
+                type,
+                timestamp: history.created || '',
+                author: historyAuthor,
+                field,
+                from: item.fromString ?? undefined,
+                to: item.toString ?? undefined,
+            });
+        }
+    }
+    // --- Convert comments to ActivityEntry list ---
+    const commentActivities = allApiComments.map((c) => {
+        const isUpdated = c.created !== c.updated;
+        return {
+            id: c.id || '',
+            type: isUpdated ? 'comment_updated' : 'comment_added',
+            timestamp: isUpdated ? c.updated : c.created,
+            author: {
+                accountId: c.author?.accountId || '',
+                displayName: c.author?.displayName || 'Unknown',
+                emailAddress: c.author?.emailAddress,
+            },
+            commentBody: convertADFToMarkdown(c.body) || '',
+        };
+    });
+    // --- Merge and sort by timestamp descending ---
+    let activities = [...changelogActivities, ...commentActivities];
+    activities.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    const totalChanges = activities.length;
+    // --- Apply filters ---
+    if (sinceDate) {
+        activities = activities.filter(a => new Date(a.timestamp).getTime() >= sinceDate);
+    }
+    if (typeFilter) {
+        activities = activities.filter(a => typeFilter.has(a.type));
+    }
+    if (author) {
+        const authorLower = author.toLowerCase();
+        activities = activities.filter(a => a.author.displayName.toLowerCase().includes(authorLower) ||
+            (a.author.emailAddress && a.author.emailAddress.toLowerCase().includes(authorLower)) ||
+            a.author.accountId.toLowerCase().includes(authorLower));
+    }
+    // --- Apply limit ---
+    const hasMore = activities.length > limit;
+    activities = activities.slice(0, limit);
+    return {
+        issueKey,
+        activities,
+        totalChanges,
+        hasMore,
+    };
+}
 /**
  * Delete an attachment by ID
  */

package/dist/lib/validation.js

@@ -254,3 +254,20 @@ export const AttachDownloadSchema = z.object({
     id: z.string().trim().min(1, 'Attachment ID is required'),
     output: z.string().trim().optional(),
 });
+// =============================================================================
+// ISSUE COMMENTS / ACTIVITY SCHEMAS
+// =============================================================================
+export const CommentsListSchema = z.object({
+    issueKey: z.string().trim().min(1, 'Issue key is required').pipe(IssueKeySchema),
+    limit: z.number().int().positive().optional(),
+    since: z.string().datetime({ offset: true, message: 'since must be a valid ISO 8601 datetime (e.g. 2024-01-01T00:00:00Z)' }).optional(),
+    reverse: z.boolean().optional(),
+});
+export const ActivityFeedSchema = z.object({
+    issueKey: z.string().trim().min(1, 'Issue key is required').pipe(IssueKeySchema),
+    since: z.string().datetime({ offset: true, message: 'since must be a valid ISO 8601 datetime (e.g. 2024-01-01T00:00:00Z)' }).optional(),
+    limit: z.number().int().positive().optional(),
+    types: z.string().optional(),
+    author: z.string().optional(),
+    compact: z.boolean().optional(),
+});

package/package.json

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