jira-ai 0.9.97 → 0.9.98

package/README.md

@@ -112,6 +112,50 @@ Discover available fields for a project (including custom fields):
 jira-ai project fields PROJ --type Task
 ```
 
+### Transition Issues
+
+Change the status of an issue:
+```bash
+jira-ai issue transition PROJ-123 "In Progress"
+```
+
+Add a comment and resolution during transition:
+```bash
+jira-ai issue transition PROJ-123 Done --resolution Done --comment "Completed the feature."
+```
+
+Change assignee and fix version during transition:
+```bash
+jira-ai issue transition PROJ-123 "In Review" --assignee "Jane Smith" --fix-version "v2.0"
+```
+
+Set a custom field during transition:
+```bash
+jira-ai issue transition PROJ-123 Done --custom-field "Story Points=5"
+```
+
+Pass a comment from a file (useful for long comments):
+```bash
+jira-ai issue transition PROJ-123 Done --comment-file ./release-notes.md
+```
+
+Discover which transitions are available and what fields they require:
+```bash
+jira-ai issue transitions PROJ-123
+```
+
+Only show transitions that have required fields:
+```bash
+jira-ai issue transitions PROJ-123 --required-only
+```
+
+Get structured output for scripting:
+```bash
+jira-ai --json 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.
+
 ## 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

@@ -19,7 +19,7 @@ import { createIssueLinkCommand } from './commands/create-issue-link.js';
 import { deleteIssueLinkCommand } from './commands/delete-issue-link.js';
 import { listLinkTypesCommand } from './commands/list-link-types.js';
 import { createTaskCommand } from './commands/create-task.js';
-import { transitionCommand } from './commands/transition.js';
+import { transitionCommand, listTransitionsCommand } from './commands/transition.js';
 import { issueAssignCommand } from './commands/issue.js';
 import { getIssueStatisticsCommand } from './commands/get-issue-statistics.js';
 import { getPersonWorklogCommand } from './commands/get-person-worklog.js';
@@ -144,7 +144,29 @@ issue
 issue
     .command('transition <issue-id> <to-status>')
     .description('Change the status of a Jira issue. The <to-status> can be either the status name or ID.')
-    .action(withPermission('issue.transition', transitionCommand, {
+    .option('--resolution <name>', 'Resolution name (e.g., "Done", "Won\'t Do")')
+    .option('--comment <text>', 'Add a comment (markdown) during transition')
+    .option('--comment-file <path>', 'Read comment from a markdown file (mutually exclusive with --comment)')
+    .option('--assignee <email-or-name>', 'Assignee (accountid:<id> or display name)')
+    .option('--fix-version <name>', 'Fix version name')
+    .option('--custom-field <entry>', 'Custom field as "Field Name=value" (repeatable)', (v, acc) => { acc.push(v); return acc; }, [])
+    .action(withPermission('issue.transition', (taskId, toStatus, opts) => transitionCommand(taskId, toStatus, {
+    resolution: opts.resolution,
+    comment: opts.comment,
+    commentFile: opts.commentFile,
+    assignee: opts.assignee,
+    fixVersion: opts.fixVersion,
+    customFields: opts.customField,
+}), {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+issue
+    .command('transitions <issue-id>')
+    .description('List available transitions for a Jira issue, including required fields.')
+    .option('--required-only', 'Only show transitions that have required fields')
+    .action(withPermission('issue.transition', (issueId, opts) => listTransitionsCommand(issueId, {
+    requiredOnly: opts.requiredOnly,
+}), {
     validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
 }));
 issue

package/dist/commands/transition.js

@@ -1,9 +1,17 @@
 import chalk from 'chalk';
-import { getIssueTransitions, transitionIssue, validateIssuePermissions } from '../lib/jira-client.js';
+import * as fs from 'fs';
+import { getIssueTransitions, transitionIssue, validateIssuePermissions, resolveUserByName } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 import { outputResult } from '../lib/json-mode.js';
-export async function transitionCommand(taskId, toStatus) {
+import { markdownToAdf } from 'marklassian';
+import { FieldResolver } from '../lib/field-resolver.js';
+import { processMentionsInADF } from '../lib/adf-mentions.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
     ui.startSpinner(`Validating permissions for ${taskId}...`);
     await validateIssuePermissions(taskId, 'transition');
@@ -31,8 +39,66 @@ export async function transitionCommand(taskId, toStatus) {
             });
         }
         const transition = matchingTransitions[0];
+        // Build optional payload if any options were provided
+        let payload;
+        if (options && Object.keys(options).some(k => options[k] !== undefined)) {
+            const fields = {};
+            const update = {};
+            if (options.resolution) {
+                fields['resolution'] = { name: options.resolution };
+            }
+            if (options.comment) {
+                let adf = markdownToAdf(options.comment);
+                adf = await processMentionsInADF(adf, resolveUserByName);
+                update['comment'] = [{ add: { body: adf } }];
+            }
+            else if (options.commentFile) {
+                const content = fs.readFileSync(options.commentFile, 'utf-8');
+                let adf = markdownToAdf(content);
+                adf = await processMentionsInADF(adf, resolveUserByName);
+                update['comment'] = [{ add: { body: adf } }];
+            }
+            if (options.assignee) {
+                if (options.assignee.startsWith('accountid:')) {
+                    fields['assignee'] = { accountId: options.assignee.slice('accountid:'.length) };
+                }
+                else {
+                    const accountId = await resolveUserByName(options.assignee);
+                    if (!accountId) {
+                        throw new CommandError(`Could not resolve user: "${options.assignee}". Check the display name and try again.`);
+                    }
+                    fields['assignee'] = { accountId };
+                }
+            }
+            if (options.fixVersion) {
+                fields['fixVersions'] = options.fixVersion.split(',').map((v) => ({ name: v.trim() }));
+            }
+            if (options.customFields && options.customFields.length > 0) {
+                const resolver = new FieldResolver();
+                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();
+                    try {
+                        fields[fieldId] = await resolver.coerceValue(fieldId, value);
+                    }
+                    catch {
+                        // Fall back to raw string if field schema is not accessible
+                        fields[fieldId] = value;
+                    }
+                }
+            }
+            payload = {
+                ...(Object.keys(fields).length > 0 && { fields }),
+                ...(Object.keys(update).length > 0 && { update }),
+            };
+            if (Object.keys(payload).length === 0)
+                payload = undefined;
+        }
         ui.startSpinner(`Transitioning ${taskId} to ${transition.to.name}...`);
-        await transitionIssue(taskId, transition.id);
+        await transitionIssue(taskId, transition.id, payload);
         ui.succeedSpinner(chalk.green(`Issue ${taskId} successfully transitioned to ${transition.to.name}.`));
         outputResult({ success: true, issueKey: taskId, status: transition.to.name }, (data) => chalk.green(`Issue ${data.issueKey} successfully transitioned to ${data.status}.`));
     }
@@ -55,3 +121,27 @@ export async function transitionCommand(taskId, toStatus) {
         throw new CommandError(`Failed to transition issue: ${error.message}`, { hints });
     }
 }
+export async function listTransitionsCommand(issueKey, options) {
+    await validateIssuePermissions(issueKey, 'transition');
+    const transitions = await getIssueTransitions(issueKey);
+    let rows = transitions.map((t) => {
+        const requiredFieldNames = t.fields
+            ? Object.entries(t.fields)
+                .filter(([, f]) => f.required)
+                .map(([key]) => key)
+            : [];
+        return {
+            id: t.id,
+            name: t.name,
+            to: t.to.name,
+            requiredFields: requiredFieldNames.length > 0 ? requiredFieldNames.join(', ') : '(none)',
+        };
+    });
+    if (options?.requiredOnly) {
+        rows = rows.filter((r) => r.requiredFields !== '(none)');
+    }
+    outputResult(rows, (data) => {
+        const lines = data.map((r) => `  ${r.id.padEnd(6)} ${r.name.padEnd(30)} → ${r.to.padEnd(20)} [required: ${r.requiredFields}]`);
+        return lines.join('\n');
+    });
+}

package/dist/lib/jira-client.js

@@ -463,6 +463,7 @@ export async function getIssueTransitions(issueIdOrKey) {
     const client = getJiraClient();
     const response = await client.issues.getTransitions({
         issueIdOrKey,
+        expand: "transitions.fields",
     });
     return (response.transitions || []).map((t) => ({
         id: t.id || '',
@@ -471,18 +472,21 @@ export async function getIssueTransitions(issueIdOrKey) {
             id: t.to?.id || '',
             name: t.to?.name || '',
         },
+        fields: t.fields,
     }));
 }
 /**
  * Perform a transition on an issue
  */
-export async function transitionIssue(issueIdOrKey, transitionId) {
+export async function transitionIssue(issueIdOrKey, transitionId, payload) {
     const client = getJiraClient();
     await client.issues.doTransition({
         issueIdOrKey,
         transition: {
             id: transitionId,
         },
+        ...(payload?.fields && { fields: payload.fields }),
+        ...(payload?.update && { update: payload.update }),
     });
 }
 /**

package/package.json

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