jira-ai 1.4.0 → 1.6.0

package/README.md

@@ -49,6 +49,34 @@ 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`, `issue transition`, and `issue worklog add/update/delete`. 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
+jira-ai issue worklog add PROJ-123 --time 2h --comment "Debugging" --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`. Worklog dry-run: `issue worklog add`, `issue worklog update`, `issue worklog delete`.
+
 ### 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 +175,108 @@ 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`
+
+### Worklog Management
+
+Log time against issues with full CRUD support:
+
+```bash
+jira-ai issue worklog add PROJ-123 --time 2h
+```
+
+Add a comment and specify when the work started:
+
+```bash
+jira-ai issue worklog add PROJ-123 --time 1d2h30m --comment "Backend refactor" --started "2026-04-15T09:00:00+02:00"
+```
+
+The `--started` flag accepts any standard ISO 8601 timestamp. Timezone offsets are automatically normalized to Jira's required format (`yyyy-MM-dd'T'HH:mm:ss.SSS±HHMM`):
+
+- `2026-04-15T07:00:00Z` → `2026-04-15T07:00:00.000+0000`
+- `2026-04-15T10:00:00+03:00` → `2026-04-15T10:00:00.000+0300`
+- `2026-04-15T07:00:00-05:30` → `2026-04-15T07:00:00.000-0530`
+
+When omitted, `--started` defaults to the current time.
+
+Log time with estimate adjustment (`--adjust-estimate` accepts `auto`, `new`, `leave`, or `manual`):
+
+```bash
+jira-ai issue worklog add PROJ-123 --time 4h --adjust-estimate new --new-estimate 2d
+```
+
+Use `--reduce-by` with `--adjust-estimate manual` to decrease the remaining estimate:
+
+```bash
+jira-ai issue worklog add PROJ-123 --time 3h --adjust-estimate manual --reduce-by 2h
+```
+
+List worklogs for an issue:
+
+```bash
+jira-ai issue worklog list PROJ-123
+```
+
+Filter by time range or author:
+
+```bash
+jira-ai issue worklog list PROJ-123 --started-after 1713139200000 --started-before 1715731200000
+jira-ai issue worklog list PROJ-123 --author-account-id 557058:abc123-def456-ghi789
+```
+
+Update an existing worklog:
+
+```bash
+jira-ai issue worklog update PROJ-123 --id 12345 --time 3h --comment "Updated after review"
+```
+
+Delete a worklog (use `--increase-by` with `--adjust-estimate manual` to restore estimate):
+
+```bash
+jira-ai issue worklog delete PROJ-123 --id 12345
+jira-ai issue worklog delete PROJ-123 --id 12345 --adjust-estimate manual --increase-by 2h
+```
+
+Preview any write operation with `--dry-run`:
+
+```bash
+jira-ai issue worklog add PROJ-123 --time 2h --dry-run
+```
+
+Duration format uses Jira-style notation: `1w` (5 working days), `1d` (8 hours), `1h`, `30m`, or combinations like `1d2h30m`.
+
 ## 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,9 @@ 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 { issueWorklogListCommand, issueWorklogAddCommand, issueWorklogUpdateCommand, issueWorklogDeleteCommand, } from './commands/issue-worklog.js';
 import { aboutCommand } from './commands/about.js';
 import { authCommand } from './commands/auth.js';
 import { settingsCommand } from './commands/settings.js';
@@ -208,6 +211,123 @@ 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 worklog subcommands
+const worklog = issue
+    .command('worklog')
+    .description('Manage worklogs for a Jira issue');
+worklog
+    .command('list <issue-id>')
+    .description('List all worklogs for a Jira issue.')
+    .option('--started-after <timestamp>', 'Only return worklogs started at or after this UNIX timestamp (ms)')
+    .option('--started-before <timestamp>', 'Only return worklogs started before this UNIX timestamp (ms)')
+    .option('--author-account-id <accountId>', 'Filter by author account ID')
+    .action(withPermission('issue.worklog.list', (issueKey, options) => {
+    return issueWorklogListCommand({
+        issueKey,
+        startedAfter: options.startedAfter ? parseInt(options.startedAfter, 10) : undefined,
+        startedBefore: options.startedBefore ? parseInt(options.startedBefore, 10) : undefined,
+        authorAccountId: options.authorAccountId,
+    });
+}, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+worklog
+    .command('add <issue-id>')
+    .description('Log time against a Jira issue.')
+    .requiredOption('--time <duration>', 'Time to log (e.g. 1h, 30m, 1d2h30m, 1w)')
+    .option('--comment <text>', 'Optional comment for this worklog entry')
+    .option('--started <datetime>', 'When the work started (ISO 8601, defaults to now). Timezone offsets are auto-normalized.')
+    .option('--adjust-estimate <method>', 'Estimate adjustment: auto, new, leave, manual')
+    .option('--new-estimate <duration>', 'New remaining estimate (use with --adjust-estimate new or manual)')
+    .option('--reduce-by <duration>', 'Reduce remaining estimate by this amount (use with --adjust-estimate manual)')
+    .action(withPermission('issue.worklog.add', (issueKey, options) => {
+    return issueWorklogAddCommand({
+        issueKey,
+        time: options.time,
+        comment: options.comment,
+        started: options.started,
+        adjustEstimate: options.adjustEstimate,
+        newEstimate: options.newEstimate,
+        reduceBy: options.reduceBy,
+    });
+}, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+worklog
+    .command('update <issue-id>')
+    .description('Update an existing worklog entry.')
+    .requiredOption('--id <worklog-id>', 'ID of the worklog to update')
+    .option('--time <duration>', 'New time spent (e.g. 1h, 30m, 1d)')
+    .option('--comment <text>', 'New comment for this worklog')
+    .option('--started <datetime>', 'New start time (ISO 8601). Timezone offsets are auto-normalized.')
+    .option('--adjust-estimate <method>', 'Estimate adjustment: auto, new, leave, manual')
+    .option('--new-estimate <duration>', 'New remaining estimate')
+    .action(withPermission('issue.worklog.update', (issueKey, options) => {
+    return issueWorklogUpdateCommand({
+        issueKey,
+        id: options.id,
+        time: options.time,
+        comment: options.comment,
+        started: options.started,
+        adjustEstimate: options.adjustEstimate,
+        newEstimate: options.newEstimate,
+    });
+}, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+worklog
+    .command('delete <issue-id>')
+    .description('Delete a worklog entry from a Jira issue.')
+    .requiredOption('--id <worklog-id>', 'ID of the worklog to delete')
+    .option('--adjust-estimate <method>', 'Estimate adjustment: auto, new, leave, manual')
+    .option('--new-estimate <duration>', 'New remaining estimate (use with --adjust-estimate new)')
+    .option('--increase-by <duration>', 'Increase remaining estimate by this amount')
+    .action(withPermission('issue.worklog.delete', (issueKey, options) => {
+    return issueWorklogDeleteCommand({
+        issueKey,
+        id: options.id,
+        adjustEstimate: options.adjustEstimate,
+        newEstimate: options.newEstimate,
+        increaseBy: options.increaseBy,
+    });
+}, {
+    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/commands/issue-worklog.js

@@ -0,0 +1,162 @@
+import { getIssueWorklogsList, addWorklogEntry, updateWorklogEntry, deleteWorklogEntry, } from '../lib/jira-client.js';
+import { CommandError } from '../lib/errors.js';
+import { outputResult } from '../lib/json-mode.js';
+import { isDryRun, formatDryRunResult } from '../lib/dry-run.js';
+import { parseDuration, normalizeJiraTimestamp } from '../lib/utils.js';
+export async function issueWorklogListCommand(options) {
+    const { issueKey, startedAfter, startedBefore, authorAccountId } = options;
+    const filterOptions = {};
+    if (startedAfter !== undefined)
+        filterOptions.startedAfter = startedAfter;
+    if (startedBefore !== undefined)
+        filterOptions.startedBefore = startedBefore;
+    if (authorAccountId !== undefined)
+        filterOptions.authorAccountId = authorAccountId;
+    try {
+        const result = await getIssueWorklogsList(issueKey, filterOptions);
+        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 worklogs on this issue');
+        }
+        throw new CommandError(`Failed to list worklogs: ${error.message}`, { hints });
+    }
+}
+export async function issueWorklogAddCommand(options) {
+    const { issueKey, time, comment, started, adjustEstimate, newEstimate, reduceBy } = options;
+    const timeSpentSeconds = parseDuration(time);
+    if (timeSpentSeconds === null) {
+        throw new CommandError(`Invalid duration: "${time}". Use Jira format e.g. 1h, 30m, 1d2h30m, 1w.`, { hints: ['Examples: 1h, 30m, 1d, 1w, 1d2h30m'] });
+    }
+    if (adjustEstimate === 'new' && !newEstimate) {
+        throw new CommandError('--new-estimate is required when --adjust-estimate is "new"', {
+            hints: ['Example: --adjust-estimate new --new-estimate 5h']
+        });
+    }
+    if (adjustEstimate === 'manual' && !newEstimate && !reduceBy) {
+        throw new CommandError('--new-estimate or --reduce-by is required when --adjust-estimate is "manual"', {
+            hints: ['Example: --adjust-estimate manual --reduce-by 1h']
+        });
+    }
+    if (isDryRun()) {
+        formatDryRunResult('issue worklog add', issueKey, { timeSpentSeconds, comment, started, adjustEstimate, newEstimate, reduceBy });
+        return;
+    }
+    try {
+        const result = await addWorklogEntry(issueKey, {
+            timeSpentSeconds,
+            comment,
+            started: started !== undefined ? normalizeJiraTimestamp(started) : undefined,
+            adjustEstimate,
+            newEstimate,
+            reduceBy,
+        });
+        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 log work on this issue');
+        }
+        throw new CommandError(`Failed to add worklog: ${error.message}`, { hints });
+    }
+}
+export async function issueWorklogUpdateCommand(options) {
+    const { issueKey, id, time, comment, started, adjustEstimate, newEstimate } = options;
+    if (time === undefined && comment === undefined && started === undefined) {
+        throw new CommandError('At least one of --time, --comment, or --started must be provided.');
+    }
+    let timeSpentSeconds;
+    if (time !== undefined) {
+        const parsed = parseDuration(time);
+        if (parsed === null) {
+            throw new CommandError(`Invalid duration: "${time}". Use Jira format e.g. 1h, 30m, 1d2h30m, 1w.`, { hints: ['Examples: 1h, 30m, 1d, 1w, 1d2h30m'] });
+        }
+        timeSpentSeconds = parsed;
+    }
+    if (adjustEstimate === 'new' && !newEstimate) {
+        throw new CommandError('--new-estimate is required when --adjust-estimate is "new"', {
+            hints: ['Example: --adjust-estimate new --new-estimate 5h']
+        });
+    }
+    if (adjustEstimate === 'manual' && !newEstimate) {
+        throw new CommandError('--new-estimate is required when --adjust-estimate is "manual"', {
+            hints: ['Example: --adjust-estimate manual --new-estimate 5h']
+        });
+    }
+    if (isDryRun()) {
+        formatDryRunResult('issue worklog update', `${issueKey} / worklog ${id}`, { timeSpentSeconds, comment, started, adjustEstimate, newEstimate });
+        return;
+    }
+    try {
+        const result = await updateWorklogEntry(issueKey, id, {
+            timeSpentSeconds,
+            comment,
+            started: started !== undefined ? normalizeJiraTimestamp(started) : undefined,
+            adjustEstimate,
+            newEstimate,
+        });
+        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 and worklog ID are correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to update this worklog');
+        }
+        throw new CommandError(`Failed to update worklog: ${error.message}`, { hints });
+    }
+}
+export async function issueWorklogDeleteCommand(options) {
+    const { issueKey, id, adjustEstimate, newEstimate, increaseBy } = options;
+    if (adjustEstimate === 'new' && !newEstimate) {
+        throw new CommandError('--new-estimate is required when --adjust-estimate is "new"', {
+            hints: ['Example: --adjust-estimate new --new-estimate 5h']
+        });
+    }
+    if (adjustEstimate === 'manual' && !newEstimate && !increaseBy) {
+        throw new CommandError('--new-estimate or --increase-by is required when --adjust-estimate is "manual"', {
+            hints: ['Example: --adjust-estimate manual --increase-by 1h']
+        });
+    }
+    if (isDryRun()) {
+        formatDryRunResult('issue worklog delete', `${issueKey} / worklog ${id}`, { id, adjustEstimate, newEstimate, increaseBy });
+        return;
+    }
+    try {
+        await deleteWorklogEntry(issueKey, id, { adjustEstimate, newEstimate, increaseBy });
+        outputResult({ deleted: true, issueKey, id });
+    }
+    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 and worklog ID are correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to delete this worklog');
+        }
+        throw new CommandError(`Failed to delete worklog: ${error.message}`, { hints });
+    }
+}

package/dist/lib/jira-client.js

@@ -1,4 +1,5 @@
 import { Version3Client } from 'jira.js';
+import { markdownToAdf } from 'marklassian';
 import { calculateStatusStatistics, convertADFToMarkdown } from './utils.js';
 import { loadCredentials } from './auth-storage.js';
 import { applyGlobalFilters, isProjectAllowed, isCommandAllowed, validateIssueAgainstFilters, getAllowedProjects } from './settings.js';
@@ -1044,6 +1045,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
  */
@@ -1051,3 +1229,140 @@ export async function deleteAttachment(issueKey, attachmentId) {
     const client = getJiraClient();
     await client.issueAttachments.removeAttachment(attachmentId);
 }
+const WORKLOG_PAGE_SIZE = 5000;
+/**
+ * List all worklogs for an issue (returns structured result).
+ * Paginates automatically through all pages and supports optional filtering.
+ */
+export async function getIssueWorklogsList(issueIdOrKey, options = {}) {
+    const { startedAfter, startedBefore, authorAccountId } = options;
+    const client = getJiraClient();
+    const allWorklogs = [];
+    let startAt = 0;
+    while (true) {
+        const params = { issueIdOrKey, startAt, maxResults: WORKLOG_PAGE_SIZE };
+        if (startedAfter !== undefined)
+            params.startedAfter = startedAfter;
+        if (startedBefore !== undefined)
+            params.startedBefore = startedBefore;
+        const response = await client.issueWorklogs.getIssueWorklog(params);
+        const page = (response.worklogs || []).map((w) => ({
+            id: w.id || '',
+            author: {
+                accountId: w.author?.accountId || '',
+                displayName: w.author?.displayName || 'Unknown',
+                emailAddress: w.author?.emailAddress,
+            },
+            comment: convertADFToMarkdown(w.comment),
+            created: w.created || '',
+            updated: w.updated || '',
+            started: w.started || '',
+            timeSpent: w.timeSpent || '',
+            timeSpentSeconds: w.timeSpentSeconds || 0,
+            issueKey: issueIdOrKey,
+        }));
+        allWorklogs.push(...page);
+        const totalOnServer = typeof response.total === 'number' ? response.total : page.length;
+        if (allWorklogs.length >= totalOnServer || page.length < WORKLOG_PAGE_SIZE)
+            break;
+        startAt += page.length;
+    }
+    const filtered = authorAccountId
+        ? allWorklogs.filter(w => w.author.accountId === authorAccountId)
+        : allWorklogs;
+    return {
+        issueKey: issueIdOrKey,
+        worklogs: filtered,
+        total: filtered.length,
+    };
+}
+/**
+ * Add a worklog entry to an issue
+ */
+export async function addWorklogEntry(issueIdOrKey, options) {
+    const client = getJiraClient();
+    const { timeSpentSeconds, comment, started, adjustEstimate, newEstimate, reduceBy } = options;
+    const params = {
+        issueIdOrKey,
+        timeSpentSeconds,
+        comment: comment ? markdownToAdf(comment) : undefined,
+        started: started || new Date().toISOString().replace('Z', '+0000'),
+    };
+    if (adjustEstimate)
+        params.adjustEstimate = adjustEstimate;
+    if (newEstimate)
+        params.newEstimate = newEstimate;
+    if (reduceBy)
+        params.reduceBy = reduceBy;
+    const w = await client.issueWorklogs.addWorklog(params);
+    return {
+        id: w.id || '',
+        author: {
+            accountId: w.author?.accountId || '',
+            displayName: w.author?.displayName || 'Unknown',
+            emailAddress: w.author?.emailAddress,
+        },
+        comment: convertADFToMarkdown(w.comment),
+        created: w.created || '',
+        updated: w.updated || '',
+        started: w.started || '',
+        timeSpent: w.timeSpent || '',
+        timeSpentSeconds: w.timeSpentSeconds || 0,
+        issueKey: issueIdOrKey,
+    };
+}
+/**
+ * Update an existing worklog entry
+ */
+export async function updateWorklogEntry(issueIdOrKey, worklogId, options) {
+    const client = getJiraClient();
+    const { timeSpentSeconds, comment, started, adjustEstimate, newEstimate } = options;
+    const params = {
+        issueIdOrKey,
+        id: worklogId,
+    };
+    if (timeSpentSeconds !== undefined)
+        params.timeSpentSeconds = timeSpentSeconds;
+    if (comment !== undefined)
+        params.comment = markdownToAdf(comment);
+    if (started !== undefined)
+        params.started = started;
+    if (adjustEstimate)
+        params.adjustEstimate = adjustEstimate;
+    if (newEstimate)
+        params.newEstimate = newEstimate;
+    const w = await client.issueWorklogs.updateWorklog(params);
+    return {
+        id: w.id || worklogId,
+        author: {
+            accountId: w.author?.accountId || '',
+            displayName: w.author?.displayName || 'Unknown',
+            emailAddress: w.author?.emailAddress,
+        },
+        comment: convertADFToMarkdown(w.comment),
+        created: w.created || '',
+        updated: w.updated || '',
+        started: w.started || '',
+        timeSpent: w.timeSpent || '',
+        timeSpentSeconds: w.timeSpentSeconds || 0,
+        issueKey: issueIdOrKey,
+    };
+}
+/**
+ * Delete a worklog entry
+ */
+export async function deleteWorklogEntry(issueIdOrKey, worklogId, options = {}) {
+    const client = getJiraClient();
+    const { adjustEstimate, newEstimate, increaseBy } = options;
+    const params = {
+        issueIdOrKey,
+        id: worklogId,
+    };
+    if (adjustEstimate)
+        params.adjustEstimate = adjustEstimate;
+    if (newEstimate)
+        params.newEstimate = newEstimate;
+    if (increaseBy)
+        params.increaseBy = increaseBy;
+    await client.issueWorklogs.deleteWorklog(params);
+}

package/dist/lib/utils.js

@@ -152,3 +152,42 @@ export function parseTimeframe(timeframe) {
 export function formatDateForJql(date) {
     return date.toISOString().split('T')[0];
 }
+/**
+ * Normalize an ISO-8601 timestamp to the format Jira accepts: yyyy-MM-dd'T'HH:mm:ss.SSSZ
+ * - No colon in timezone offset, no Z suffix, milliseconds always present.
+ * - "2026-04-15T07:00:00.000Z"     → "2026-04-15T07:00:00.000+0000"
+ * - "2026-04-15T10:00:00+03:00"    → "2026-04-15T10:00:00.000+0300"
+ * - "2026-04-15T07:00:00Z"         → "2026-04-15T07:00:00.000+0000"
+ * - "2026-04-15T07:00:00.000+0000" → unchanged
+ */
+export function normalizeJiraTimestamp(timestamp) {
+    // Replace Z suffix with +0000
+    let normalized = timestamp.replace(/Z$/, '+0000');
+    // Remove colon from timezone offset: +HH:MM → +HHMM or -HH:MM → -HHMM
+    normalized = normalized.replace(/([+-])(\d{2}):(\d{2})$/, '$1$2$3');
+    // Add .000 milliseconds if missing (before the timezone offset)
+    normalized = normalized.replace(/(\d{2}:\d{2}:\d{2})([+-]\d{4})$/, '$1.000$2');
+    return normalized;
+}
+/**
+ * Parse a Jira-style duration string into total seconds.
+ * Supports: 1w, 2d, 3h, 30m and combinations like 1d2h30m.
+ * Conversion: 1w = 5d, 1d = 8h.
+ * Returns null for invalid input.
+ */
+export function parseDuration(duration) {
+    const match = duration.match(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?$/);
+    if (!match || match[0] === '')
+        return null;
+    const weeks = parseInt(match[1] || '0', 10);
+    const days = parseInt(match[2] || '0', 10);
+    const hours = parseInt(match[3] || '0', 10);
+    const minutes = parseInt(match[4] || '0', 10);
+    const totalSeconds = weeks * 5 * 8 * 3600 +
+        days * 8 * 3600 +
+        hours * 3600 +
+        minutes * 60;
+    if (totalSeconds === 0)
+        return null;
+    return totalSeconds;
+}

package/dist/lib/validation.js

@@ -254,3 +254,57 @@ 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(),
+});
+// =============================================================================
+// WORKLOG SCHEMAS
+// =============================================================================
+export const DurationSchema = z
+    .string()
+    .regex(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?$/, 'Duration must be in Jira format: e.g. 1h, 30m, 1d2h30m, 1w');
+export const WorklogListSchema = z.object({
+    issueKey: z.string().trim().min(1, 'Issue key is required').pipe(IssueKeySchema),
+    startedAfter: z.number().int().positive().optional(),
+    startedBefore: z.number().int().positive().optional(),
+    authorAccountId: z.string().optional(),
+});
+export const WorklogAddSchema = z.object({
+    issueKey: z.string().trim().min(1, 'Issue key is required').pipe(IssueKeySchema),
+    time: DurationSchema,
+    comment: z.string().optional(),
+    started: z.string().optional(),
+    adjustEstimate: z.enum(['auto', 'new', 'leave', 'manual']).optional(),
+    newEstimate: z.string().optional(),
+    reduceBy: z.string().optional(),
+});
+export const WorklogUpdateSchema = z.object({
+    issueKey: z.string().trim().min(1, 'Issue key is required').pipe(IssueKeySchema),
+    id: z.string().min(1, 'Worklog ID is required'),
+    time: DurationSchema.optional(),
+    comment: z.string().optional(),
+    started: z.string().optional(),
+    adjustEstimate: z.enum(['auto', 'new', 'leave', 'manual']).optional(),
+    newEstimate: z.string().optional(),
+});
+export const WorklogDeleteSchema = z.object({
+    issueKey: z.string().trim().min(1, 'Issue key is required').pipe(IssueKeySchema),
+    id: z.string().min(1, 'Worklog ID is required'),
+    adjustEstimate: z.enum(['auto', 'new', 'leave', 'manual']).optional(),
+    newEstimate: z.string().optional(),
+    increaseBy: z.string().optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jira-ai",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "AI friendly Jira CLI to save context",
   "type": "module",
   "main": "dist/cli.js",
@@ -48,12 +48,13 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "adf-to-markdown": "^1.0.1",
     "commander": "^11.0.0",
     "confluence.js": "^2.1.0",
     "dotenv": "^17.2.3",
     "html-entities": "^2.6.0",
-"jira.js": "^5.2.2",
+    "jira.js": "^5.2.2",
     "js-yaml": "^4.1.1",
     "marklassian": "^1.0.0",
     "zod": "^4.3.5"