jira-ai 1.3.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';
@@ -48,6 +50,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) {
@@ -207,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/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-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/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

@@ -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.3.0",
+  "version": "1.5.0",
   "description": "AI friendly Jira CLI to save context",
   "type": "module",
   "main": "dist/cli.js",