jira-ai 0.9.97 → 0.9.99

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,13 +19,16 @@ 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';
 import { isCommandAllowed, getAllowedCommands } from './lib/settings.js';
 import { confluenceGetPageCommand, confluenceListSpacesCommand, confluenceGetSpacePagesHierarchyCommand, confluenceAddCommentCommand, confluenceCreatePageCommand, confluenceUpdateDescriptionCommand, confluenceSearchCommand } from './commands/confluence.js';
 import { epicListCommand, epicGetCommand, epicCreateCommand, epicUpdateCommand, epicIssuesCommand, epicLinkCommand, epicUnlinkCommand, epicProgressCommand, } from './commands/epic.js';
+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 { aboutCommand } from './commands/about.js';
 import { authCommand } from './commands/auth.js';
 import { settingsCommand } from './commands/settings.js';
@@ -35,7 +38,7 @@ import { CliError } from './types/errors.js';
 import { CommandError } from './lib/errors.js';
 import { ui } from './lib/ui.js';
 import { initJsonMode, outputError } from './lib/json-mode.js';
-import { CreateTaskSchema, UpdateDescriptionSchema, ProjectFieldsSchema, ConfluenceAddCommentSchema, RunJqlSchema, GetPersonWorklogSchema, GetIssueStatisticsSchema, EpicListSchema, EpicCreateSchema, EpicUpdateSchema, EpicLinkSchema, EpicMaxSchema, validateOptions, IssueKeySchema, ProjectKeySchema, TimeframeSchema } from './lib/validation.js';
+import { CreateTaskSchema, UpdateDescriptionSchema, ProjectFieldsSchema, ConfluenceAddCommentSchema, RunJqlSchema, GetPersonWorklogSchema, GetIssueStatisticsSchema, EpicListSchema, EpicCreateSchema, EpicUpdateSchema, EpicLinkSchema, EpicMaxSchema, validateOptions, IssueKeySchema, ProjectKeySchema, TimeframeSchema, BoardListSchema, BoardIssuesSchema, BoardRankSchema, SprintListSchema, SprintCreateSchema, SprintUpdateSchema, SprintIssuesSchema, SprintMoveSchema, BacklogMoveSchema, } from './lib/validation.js';
 import { realpathSync } from 'fs';
 // Create CLI program
 const program = new Command();
@@ -144,7 +147,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
@@ -437,6 +462,106 @@ epic
     .action(withPermission('epic.progress', epicProgressCommand, {
     validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
 }));
+// =============================================================================
+// BOARD COMMANDS
+// =============================================================================
+const board = program
+    .command('board')
+    .description('Manage Jira agile boards');
+board
+    .command('list')
+    .description('List all boards, optionally filtered by project or type.')
+    .option('--project <key>', 'Filter by project key')
+    .option('--type <type>', 'Filter by board type (scrum, kanban)')
+    .action(withPermission('board.list', boardListCommand, { schema: BoardListSchema }));
+board
+    .command('get <board-id>')
+    .description('Get details of a specific board.')
+    .action(withPermission('board.get', (boardId) => boardGetCommand(Number(boardId))));
+board
+    .command('config <board-id>')
+    .description('Get configuration for a board including columns and filter.')
+    .action(withPermission('board.config', (boardId) => boardConfigCommand(Number(boardId))));
+board
+    .command('issues <board-id>')
+    .description('List issues on a board.')
+    .option('--jql <jql>', 'Additional JQL filter')
+    .option('--max <n>', 'Maximum results')
+    .action(withPermission('board.issues', (boardId, options) => boardIssuesCommand(Number(boardId), { jql: options.jql, max: options.max ? Number(options.max) : undefined }), { schema: BoardIssuesSchema }));
+board
+    .command('rank')
+    .description('Rank issues on a board before or after another issue.')
+    .requiredOption('--issues <keys...>', 'Issue keys to rank')
+    .option('--before <key>', 'Rank before this issue')
+    .option('--after <key>', 'Rank after this issue')
+    .action(withPermission('board.rank', boardRankCommand, { schema: BoardRankSchema }));
+// =============================================================================
+// SPRINT COMMANDS
+// =============================================================================
+const sprint = program
+    .command('sprint')
+    .description('Manage Jira sprints');
+sprint
+    .command('list <board-id>')
+    .description('List sprints for a board.')
+    .option('--state <state>', 'Filter by state (future, active, closed)')
+    .action(withPermission('sprint.list', (boardId, options) => sprintListCommand(Number(boardId), options), { schema: SprintListSchema }));
+sprint
+    .command('get <sprint-id>')
+    .description('Get details of a specific sprint.')
+    .action(withPermission('sprint.get', (sprintId) => sprintGetCommand(Number(sprintId))));
+sprint
+    .command('create <board-id>')
+    .description('Create a new sprint on a board.')
+    .requiredOption('--name <name>', 'Sprint name')
+    .option('--goal <goal>', 'Sprint goal')
+    .option('--start <date>', 'Start date (ISO format)')
+    .option('--end <date>', 'End date (ISO format)')
+    .action(withPermission('sprint.create', (boardId, options) => sprintCreateCommand(Number(boardId), options.name, options), { schema: SprintCreateSchema }));
+sprint
+    .command('start <sprint-id>')
+    .description('Start a sprint (must be in future state).')
+    .action(withPermission('sprint.start', (sprintId) => sprintStartCommand(Number(sprintId))));
+sprint
+    .command('complete <sprint-id>')
+    .description('Complete a sprint (must be in active state).')
+    .action(withPermission('sprint.complete', (sprintId) => sprintCompleteCommand(Number(sprintId))));
+sprint
+    .command('update <sprint-id>')
+    .description('Update sprint name, goal, or dates.')
+    .option('--name <name>', 'New sprint name')
+    .option('--goal <goal>', 'New sprint goal')
+    .option('--start <date>', 'New start date (ISO format)')
+    .option('--end <date>', 'New end date (ISO format)')
+    .action(withPermission('sprint.update', (sprintId, options) => sprintUpdateCommand(Number(sprintId), options), { schema: SprintUpdateSchema }));
+sprint
+    .command('delete <sprint-id>')
+    .description('Delete a sprint.')
+    .action(withPermission('sprint.delete', (sprintId) => sprintDeleteCommand(Number(sprintId))));
+sprint
+    .command('issues <sprint-id>')
+    .description('List issues in a sprint.')
+    .option('--jql <jql>', 'Additional JQL filter')
+    .option('--max <n>', 'Maximum results')
+    .action(withPermission('sprint.issues', (sprintId, options) => sprintIssuesCommand(Number(sprintId), { jql: options.jql, max: options.max ? Number(options.max) : undefined }), { schema: SprintIssuesSchema }));
+sprint
+    .command('move <sprint-id>')
+    .description('Move issues into a sprint.')
+    .requiredOption('--issues <keys...>', 'Issue keys to move')
+    .option('--before <key>', 'Rank before this issue')
+    .option('--after <key>', 'Rank after this issue')
+    .action(withPermission('sprint.move', (sprintId, options) => sprintMoveCommand(Number(sprintId), options), { schema: SprintMoveSchema }));
+// =============================================================================
+// BACKLOG COMMANDS
+// =============================================================================
+const backlog = program
+    .command('backlog')
+    .description('Manage Jira backlog');
+backlog
+    .command('move')
+    .description('Move issues to the backlog.')
+    .requiredOption('--issues <keys...>', 'Issue keys to move to backlog')
+    .action(withPermission('board.backlog', backlogMoveCommand, { schema: BacklogMoveSchema }));
 // About command (always allowed)
 program
     .command('about')
@@ -471,6 +596,9 @@ Command Groups (use in allowed-commands):
   user        - me, search, worklog
   epic        - list, get, create, update, issues, link, unlink, progress
   confl       - get, spaces, pages, create, comment, update
+  board       - list, get, config, issues, rank
+  sprint      - list, get, create, start, complete, update, delete, issues, move
+  backlog     - move
 
 Examples:
   - "issue"           → allows all issue subcommands

package/dist/commands/backlog.js

@@ -0,0 +1,21 @@
+import chalk from 'chalk';
+import { moveIssuesToBacklog } from '../lib/agile-client.js';
+import { requirePermission } from '../lib/permissions.js';
+import { CommandError } from '../lib/errors.js';
+import { ui } from '../lib/ui.js';
+// backlog move --issues <keys>
+export async function backlogMoveCommand(options) {
+    requirePermission('board.backlog');
+    if (!options.issues || options.issues.length === 0) {
+        throw new CommandError('At least one issue key is required.', { hints: ['Provide issue keys with --issues'] });
+    }
+    if (options.issues.length > 50) {
+        throw new CommandError('Cannot move more than 50 issues at once.', {
+            hints: ['Split your issue list into batches of 50 or fewer'],
+        });
+    }
+    ui.startSpinner(`Moving ${options.issues.length} issue(s) to backlog...`);
+    await moveIssuesToBacklog(options.issues);
+    ui.succeedSpinner(chalk.green(`Moved ${options.issues.length} issue(s) to backlog.`));
+    console.log();
+}

package/dist/commands/board.js

@@ -0,0 +1,120 @@
+import chalk from 'chalk';
+import { getBoards, getBoard, getBoardConfig, getBoardIssues, rankIssues } from '../lib/agile-client.js';
+import { requirePermission } from '../lib/permissions.js';
+import { CommandError } from '../lib/errors.js';
+import { ui } from '../lib/ui.js';
+// board list [--project <key>] [--type <type>]
+export async function boardListCommand(options) {
+    requirePermission('board.list');
+    ui.startSpinner('Fetching boards...');
+    const params = {};
+    if (options?.projectKey)
+        params.projectKeyOrId = options.projectKey;
+    if (options?.type)
+        params.type = options.type;
+    const result = await getBoards(Object.keys(params).length ? params : undefined);
+    ui.stopSpinner();
+    if (!result.values || result.values.length === 0) {
+        console.log(chalk.yellow('No boards found.'));
+        return;
+    }
+    console.log(chalk.bold(`\nBoards (${result.values.length} total)\n`));
+    result.values.forEach(board => {
+        const location = board.location?.displayName ? chalk.gray(` — ${board.location.displayName}`) : '';
+        console.log(`  ${chalk.cyan(String(board.id))}  ${board.name}${location}  ${chalk.gray(`[${board.type}]`)}`);
+    });
+    if (!result.isLast) {
+        console.log(chalk.gray('\n  (More results available — use --max to fetch more)'));
+    }
+    console.log();
+}
+// board get <board-id>
+export async function boardGetCommand(boardId) {
+    requirePermission('board.get');
+    if (boardId == null) {
+        throw new CommandError('Board ID is required.', { hints: ['Provide a numeric board ID'] });
+    }
+    ui.startSpinner(`Fetching board ${boardId}...`);
+    const board = await getBoard(boardId);
+    ui.stopSpinner();
+    console.log(chalk.bold(`\nBoard: ${board.name}`) + '\n');
+    console.log(`  ID:       ${chalk.cyan(String(board.id))}`);
+    console.log(`  Type:     ${board.type}`);
+    if (board.location?.projectKey)
+        console.log(`  Project:  ${board.location.projectKey}`);
+    if (board.location?.displayName)
+        console.log(`  Location: ${board.location.displayName}`);
+    if (board.isPrivate !== undefined)
+        console.log(`  Private:  ${board.isPrivate ? 'Yes' : 'No'}`);
+    console.log();
+}
+// board config <board-id>
+export async function boardConfigCommand(boardId) {
+    requirePermission('board.config');
+    if (boardId == null) {
+        throw new CommandError('Board ID is required.', { hints: ['Provide a numeric board ID'] });
+    }
+    ui.startSpinner(`Fetching board config for ${boardId}...`);
+    const config = await getBoardConfig(boardId);
+    ui.stopSpinner();
+    console.log(chalk.bold(`\nBoard Config: ${config.name}`) + '\n');
+    console.log(`  ID:   ${chalk.cyan(String(config.id))}`);
+    if (config.type)
+        console.log(`  Type: ${config.type}`);
+    if (config.filter)
+        console.log(`  Filter ID: ${config.filter.id}`);
+    if (config.ranking)
+        console.log(`  Rank Field: ${config.ranking.rankCustomFieldId}`);
+    if (config.columnConfig?.columns?.length) {
+        console.log(`\n  ${chalk.bold('Columns:')}`);
+        config.columnConfig.columns.forEach(col => {
+            const statuses = col.statuses?.map(s => s.id).join(', ') || 'none';
+            console.log(`    ${chalk.cyan(col.name)}  [statuses: ${statuses}]`);
+        });
+    }
+    console.log();
+}
+// board issues <board-id> [--jql <jql>] [--max <n>]
+export async function boardIssuesCommand(boardId, options) {
+    requirePermission('board.issues');
+    ui.startSpinner(`Fetching issues for board ${boardId}...`);
+    const params = {};
+    if (options?.jql)
+        params.jql = options.jql;
+    if (options?.max)
+        params.maxResults = options.max;
+    const result = await getBoardIssues(boardId, params);
+    ui.stopSpinner();
+    if (!result.issues || result.issues.length === 0) {
+        console.log(chalk.yellow('No issues found on this board.'));
+        return;
+    }
+    console.log(chalk.bold(`\nBoard Issues (${result.total} total)\n`));
+    result.issues.forEach(issue => {
+        const status = chalk.gray(`[${issue.fields.status.name}]`);
+        const assignee = issue.fields.assignee ? chalk.gray(` @${issue.fields.assignee.displayName}`) : '';
+        console.log(`  ${chalk.cyan(issue.key)}  ${issue.fields.summary}  ${status}${assignee}`);
+    });
+    console.log();
+}
+// board rank --issues <keys> --before <key> | --after <key>
+export async function boardRankCommand(options) {
+    requirePermission('board.rank');
+    if (!options.issues || options.issues.length === 0) {
+        throw new CommandError('At least one issue key is required.', { hints: ['Provide issue keys with --issues'] });
+    }
+    if (!options.before && !options.after) {
+        throw new CommandError('Either --before or --after must be specified.', {
+            hints: ['Use --before <issue-key> or --after <issue-key>'],
+        });
+    }
+    ui.startSpinner('Ranking issues...');
+    const rankOptions = {};
+    if (options.before)
+        rankOptions.rankBeforeIssue = options.before;
+    if (options.after)
+        rankOptions.rankAfterIssue = options.after;
+    await rankIssues(options.issues, rankOptions);
+    ui.succeedSpinner(chalk.green(`Ranked ${options.issues.length} issue(s) successfully.`));
+    console.log();
+}

package/dist/commands/sprint.js

@@ -0,0 +1,187 @@
+import chalk from 'chalk';
+import { getSprints, getSprint, createSprint, startSprint, completeSprint, updateSprint, deleteSprint, getSprintIssues, moveIssuesToSprint, } from '../lib/agile-client.js';
+import { requirePermission } from '../lib/permissions.js';
+import { CommandError } from '../lib/errors.js';
+import { ui } from '../lib/ui.js';
+// sprint list <board-id> [--state <state>]
+export async function sprintListCommand(boardId, options) {
+    requirePermission('sprint.list');
+    ui.startSpinner(`Fetching sprints for board ${boardId}...`);
+    const params = {};
+    if (options?.state)
+        params.state = options.state;
+    const result = await getSprints(boardId, params);
+    ui.stopSpinner();
+    if (!result.values || result.values.length === 0) {
+        console.log(chalk.yellow('No sprints found for this board.'));
+        return;
+    }
+    console.log(chalk.bold(`\nSprints (${result.values.length} total)\n`));
+    result.values.forEach(sprint => {
+        const stateColor = sprint.state === 'active' ? chalk.green : sprint.state === 'closed' ? chalk.gray : chalk.yellow;
+        const dates = sprint.startDate ? ` ${chalk.gray(`${sprint.startDate} → ${sprint.endDate || '?'}`)}` : '';
+        console.log(`  ${chalk.cyan(String(sprint.id))}  ${sprint.name}  ${stateColor(`[${sprint.state}]`)}${dates}`);
+    });
+    console.log();
+}
+// sprint get <sprint-id>
+export async function sprintGetCommand(sprintId) {
+    requirePermission('sprint.get');
+    if (sprintId == null) {
+        throw new CommandError('Sprint ID is required.', { hints: ['Provide a numeric sprint ID'] });
+    }
+    ui.startSpinner(`Fetching sprint ${sprintId}...`);
+    const sprint = await getSprint(sprintId);
+    ui.stopSpinner();
+    const stateColor = sprint.state === 'active' ? chalk.green : sprint.state === 'closed' ? chalk.gray : chalk.yellow;
+    console.log(chalk.bold(`\nSprint: ${sprint.name}`) + '\n');
+    console.log(`  ID:     ${chalk.cyan(String(sprint.id))}`);
+    console.log(`  State:  ${stateColor(sprint.state)}`);
+    if (sprint.startDate)
+        console.log(`  Start:  ${sprint.startDate}`);
+    if (sprint.endDate)
+        console.log(`  End:    ${sprint.endDate}`);
+    if (sprint.goal)
+        console.log(`  Goal:   ${sprint.goal}`);
+    if (sprint.originBoardId)
+        console.log(`  Board:  ${sprint.originBoardId}`);
+    console.log();
+}
+// sprint create <board-id> --name <name> [--goal <goal>] [--start <date>] [--end <date>]
+export async function sprintCreateCommand(boardId, name, options) {
+    requirePermission('sprint.create');
+    if (boardId == null) {
+        throw new CommandError('Board ID is required.', { hints: ['Provide a numeric board ID'] });
+    }
+    if (!name) {
+        throw new CommandError('Sprint name is required.', { hints: ['Provide a sprint name with --name'] });
+    }
+    ui.startSpinner(`Creating sprint "${name}"...`);
+    const params = {};
+    if (options?.goal)
+        params.goal = options.goal;
+    if (options?.start)
+        params.startDate = options.start;
+    if (options?.end)
+        params.endDate = options.end;
+    const sprint = await createSprint(boardId, name, params);
+    ui.succeedSpinner(chalk.green(`Sprint created: ${sprint.name} (ID: ${sprint.id})`));
+    console.log();
+}
+// sprint start <sprint-id>
+export async function sprintStartCommand(sprintId) {
+    requirePermission('sprint.start');
+    if (sprintId == null) {
+        throw new CommandError('Sprint ID is required.', { hints: ['Provide a numeric sprint ID'] });
+    }
+    ui.startSpinner(`Validating sprint ${sprintId}...`);
+    const sprintToStart = await getSprint(sprintId);
+    if (sprintToStart.state !== 'future') {
+        ui.failSpinner();
+        throw new CommandError(`Cannot start sprint in state '${sprintToStart.state}'. Only 'future' sprints can be started.`, { hints: ['Use sprint list to see available sprints and their states'] });
+    }
+    if (!sprintToStart.startDate || !sprintToStart.endDate) {
+        ui.failSpinner();
+        throw new CommandError('Cannot start sprint: start and end dates are required. Use sprint update <id> --start <date> --end <date> first.', { hints: ['Example: jira-ai sprint update <id> --start 2024-01-01 --end 2024-01-14'] });
+    }
+    ui.startSpinner(`Starting sprint ${sprintId}...`);
+    await startSprint(sprintId);
+    ui.succeedSpinner(chalk.green(`Sprint ${sprintId} started successfully.`));
+    console.log();
+}
+// sprint complete <sprint-id>
+export async function sprintCompleteCommand(sprintId) {
+    requirePermission('sprint.complete');
+    if (sprintId == null) {
+        throw new CommandError('Sprint ID is required.', { hints: ['Provide a numeric sprint ID'] });
+    }
+    ui.startSpinner(`Validating sprint ${sprintId}...`);
+    const sprintToComplete = await getSprint(sprintId);
+    if (sprintToComplete.state !== 'active') {
+        ui.failSpinner();
+        throw new CommandError(`Cannot complete sprint in state '${sprintToComplete.state}'. Only 'active' sprints can be completed.`, { hints: ['Use sprint list to see available sprints and their states'] });
+    }
+    ui.startSpinner(`Completing sprint ${sprintId}...`);
+    await completeSprint(sprintId);
+    ui.succeedSpinner(chalk.green(`Sprint ${sprintId} completed successfully.`));
+    console.log();
+}
+// sprint update <sprint-id> [--name <name>] [--goal <goal>]
+export async function sprintUpdateCommand(sprintId, options) {
+    requirePermission('sprint.update');
+    if (sprintId == null) {
+        throw new CommandError('Sprint ID is required.', { hints: ['Provide a numeric sprint ID'] });
+    }
+    if (!options?.name && !options?.goal && !options?.start && !options?.end) {
+        throw new CommandError('At least one field is required.', {
+            hints: ['Provide one or more of: --name, --goal, --start, --end'],
+        });
+    }
+    ui.startSpinner(`Updating sprint ${sprintId}...`);
+    const updates = {};
+    if (options?.name)
+        updates.name = options.name;
+    if (options?.goal)
+        updates.goal = options.goal;
+    if (options?.start)
+        updates.startDate = options.start;
+    if (options?.end)
+        updates.endDate = options.end;
+    await updateSprint(sprintId, updates);
+    ui.succeedSpinner(chalk.green(`Sprint ${sprintId} updated successfully.`));
+    console.log();
+}
+// sprint delete <sprint-id>
+export async function sprintDeleteCommand(sprintId) {
+    requirePermission('sprint.delete');
+    if (sprintId == null) {
+        throw new CommandError('Sprint ID is required.', { hints: ['Provide a numeric sprint ID'] });
+    }
+    ui.startSpinner(`Deleting sprint ${sprintId}...`);
+    await deleteSprint(sprintId);
+    ui.succeedSpinner(chalk.green(`Sprint ${sprintId} deleted successfully.`));
+    console.log();
+}
+// sprint issues <sprint-id> [--jql <jql>] [--max <n>]
+export async function sprintIssuesCommand(sprintId, options) {
+    requirePermission('sprint.issues');
+    ui.startSpinner(`Fetching issues for sprint ${sprintId}...`);
+    const params = {};
+    if (options?.jql)
+        params.jql = options.jql;
+    if (options?.max)
+        params.maxResults = options.max;
+    const result = await getSprintIssues(sprintId, params);
+    ui.stopSpinner();
+    if (!result.issues || result.issues.length === 0) {
+        console.log(chalk.yellow('No issues found in this sprint.'));
+        return;
+    }
+    console.log(chalk.bold(`\nSprint Issues (${result.total} total)\n`));
+    result.issues.forEach(issue => {
+        const status = chalk.gray(`[${issue.fields.status.name}]`);
+        console.log(`  ${chalk.cyan(issue.key)}  ${issue.fields.summary}  ${status}`);
+    });
+    console.log();
+}
+// sprint move <sprint-id> --issues <keys> [--before <key>] [--after <key>]
+export async function sprintMoveCommand(sprintId, options) {
+    requirePermission('sprint.move');
+    if (!options.issues || options.issues.length === 0) {
+        throw new CommandError('At least one issue key is required.', { hints: ['Provide issue keys with --issues'] });
+    }
+    if (options.issues.length > 50) {
+        throw new CommandError('Cannot move more than 50 issues at once.', {
+            hints: ['Split your issue list into batches of 50 or fewer'],
+        });
+    }
+    ui.startSpinner(`Moving ${options.issues.length} issue(s) to sprint ${sprintId}...`);
+    const rankOptions = {};
+    if (options.before)
+        rankOptions.rankBeforeIssue = options.before;
+    if (options.after)
+        rankOptions.rankAfterIssue = options.after;
+    await moveIssuesToSprint(sprintId, options.issues, rankOptions);
+    ui.succeedSpinner(chalk.green(`Moved ${options.issues.length} issue(s) to sprint ${sprintId}.`));
+    console.log();
+}

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/agile-client.js

@@ -0,0 +1,186 @@
+import { AgileClient } from 'jira.js';
+import { loadCredentials } from './auth-storage.js';
+import { CommandError } from './errors.js';
+import { resolveHost } from './jira-client.js';
+/**
+ * Map HTTP status codes from Jira Agile API to user-friendly CommandErrors.
+ */
+function mapAgileError(error, context) {
+    const status = error?.response?.status ?? error?.status;
+    const msg = error?.message || String(error);
+    if (status === 404) {
+        throw new CommandError(`${context} not found. Check that the ID is correct.`, {
+            hints: ['Use the list command to find valid IDs'],
+        });
+    }
+    if (status === 400) {
+        const detail = error?.response?.data?.message || error?.response?.data || '';
+        throw new CommandError(`${context} — bad request: ${detail || msg}`, {
+            hints: ['Check that all required fields are provided and the resource is in the correct state'],
+        });
+    }
+    if (status === 403) {
+        throw new CommandError(`${context} — permission denied. You do not have access to perform this action.`, {
+            hints: ['Check your Jira permissions for agile operations'],
+        });
+    }
+    throw error;
+}
+let agileClientInstance = null;
+export function __resetAgileClient__() {
+    agileClientInstance = null;
+}
+export async function getAgileClient() {
+    if (!agileClientInstance) {
+        const creds = await loadCredentials();
+        if (!creds) {
+            throw new CommandError('Jira credentials not found. Please run "jira-ai auth"');
+        }
+        const host = resolveHost(creds);
+        agileClientInstance = new AgileClient({
+            host,
+            authentication: {
+                basic: {
+                    email: creds.email,
+                    apiToken: creds.apiToken,
+                },
+            },
+        });
+    }
+    return agileClientInstance;
+}
+// Board wrappers
+export async function getBoards(options) {
+    const client = await getAgileClient();
+    return client.board.getAllBoards({ ...options });
+}
+export async function getBoard(boardId) {
+    const client = await getAgileClient();
+    try {
+        return await client.board.getBoard({ boardId });
+    }
+    catch (error) {
+        mapAgileError(error, `Board ${boardId}`);
+    }
+}
+export async function getBoardConfig(boardId) {
+    const client = await getAgileClient();
+    try {
+        return await client.board.getConfiguration({ boardId });
+    }
+    catch (error) {
+        mapAgileError(error, `Board config for ${boardId}`);
+    }
+}
+export async function getBoardIssues(boardId, options) {
+    const client = await getAgileClient();
+    try {
+        return await client.board.getIssuesForBoard({ boardId, ...options });
+    }
+    catch (error) {
+        mapAgileError(error, `Board issues for ${boardId}`);
+    }
+}
+// Sprint wrappers
+export async function getSprints(boardId, options) {
+    const client = await getAgileClient();
+    try {
+        // getAllSprints is on client.board in jira.js v5.2.2, not client.sprint
+        return await client.board.getAllSprints({ boardId, ...options });
+    }
+    catch (error) {
+        const msg = error?.message || '';
+        if (msg.toLowerCase().includes('board does not support sprints') || msg.toLowerCase().includes('does not support sprints')) {
+            throw new CommandError('This board does not support sprints. Sprint operations require a Scrum board.', {
+                hints: ['Use a Scrum board for sprint operations', 'Kanban boards do not support sprints'],
+            });
+        }
+        throw error;
+    }
+}
+export async function getSprint(sprintId) {
+    const client = await getAgileClient();
+    try {
+        return await client.sprint.getSprint({ sprintId });
+    }
+    catch (error) {
+        mapAgileError(error, `Sprint ${sprintId}`);
+    }
+}
+export async function createSprint(boardId, name, options) {
+    const client = await getAgileClient();
+    return client.sprint.createSprint({
+        originBoardId: boardId,
+        name,
+        ...options,
+    });
+}
+export async function startSprint(sprintId) {
+    const client = await getAgileClient();
+    await client.sprint.partiallyUpdateSprint({ sprintId, state: 'active' });
+}
+export async function completeSprint(sprintId) {
+    const client = await getAgileClient();
+    await client.sprint.partiallyUpdateSprint({ sprintId, state: 'closed' });
+}
+export async function updateSprint(sprintId, updates) {
+    const client = await getAgileClient();
+    await client.sprint.partiallyUpdateSprint({ sprintId, ...updates });
+}
+export async function deleteSprint(sprintId) {
+    const client = await getAgileClient();
+    try {
+        await client.sprint.deleteSprint({ sprintId });
+    }
+    catch (error) {
+        mapAgileError(error, `Sprint ${sprintId}`);
+    }
+}
+export async function getSprintIssues(sprintId, options) {
+    const client = await getAgileClient();
+    return client.sprint.getIssuesForSprint({ sprintId, ...options });
+}
+export async function moveIssuesToSprint(sprintId, issues, options) {
+    if (issues.length > 50) {
+        throw new CommandError('Cannot move more than 50 issues at once.', {
+            hints: ['Split your issue list into batches of 50 or fewer'],
+        });
+    }
+    const client = await getAgileClient();
+    try {
+        await client.sprint.moveIssuesToSprintAndRank({ sprintId, issues, ...options });
+    }
+    catch (error) {
+        mapAgileError(error, `Move issues to sprint ${sprintId}`);
+    }
+}
+// Backlog wrapper
+export async function moveIssuesToBacklog(issues) {
+    if (issues.length > 50) {
+        throw new CommandError('Cannot move more than 50 issues at once.', {
+            hints: ['Split your issue list into batches of 50 or fewer'],
+        });
+    }
+    const client = await getAgileClient();
+    try {
+        await client.backlog.moveIssuesToBacklog({ issues });
+    }
+    catch (error) {
+        mapAgileError(error, `Move issues to backlog`);
+    }
+}
+// Rank wrapper
+export async function rankIssues(issues, options) {
+    if (issues.length > 50) {
+        throw new CommandError('Cannot rank more than 50 issues at once.', {
+            hints: ['Split your issue list into batches of 50 or fewer'],
+        });
+    }
+    const client = await getAgileClient();
+    try {
+        await client.issue.rankIssues({ issues, ...options });
+    }
+    catch (error) {
+        mapAgileError(error, `Rank issues`);
+    }
+}

package/dist/lib/jira-client.js

@@ -5,7 +5,7 @@ import { applyGlobalFilters, isProjectAllowed, isCommandAllowed, validateIssueAg
 import { CommandError } from './errors.js';
 import { getEpicFields, isNextGenProject } from './epic-fields.js';
 let jiraClient = null;
-function resolveHost(creds) {
+export function resolveHost(creds) {
     if (creds.authType === 'service_account' && creds.cloudId) {
         return `https://api.atlassian.com/ex/jira/${creds.cloudId}`;
     }
@@ -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/dist/lib/permissions.js

@@ -0,0 +1,13 @@
+import { isCommandAllowed, getAllowedCommands } from './settings.js';
+import { CommandError } from './errors.js';
+/**
+ * Throws a CommandError if the given command is not allowed by current settings.
+ * Shared utility used by board, sprint, backlog, and other command modules.
+ */
+export function requirePermission(command) {
+    if (!isCommandAllowed(command)) {
+        throw new CommandError(`Command '${command}' is not allowed.`, {
+            hints: [`Allowed commands: ${getAllowedCommands().join(', ')}`, 'Update settings.yaml to enable this command.'],
+        });
+    }
+}

package/dist/lib/settings.js

@@ -39,7 +39,10 @@ export const DEFAULT_ORG_SETTINGS = {
         'issue',
         'project',
         'user',
-        'confl'
+        'confl',
+        'board',
+        'sprint',
+        'backlog',
     ],
     'allowed-confluence-spaces': ['all']
 };

package/dist/lib/validation.js

@@ -187,3 +187,56 @@ export const EpicLinkSchema = z.object({
 export const EpicMaxSchema = z.object({
     max: NumericStringSchema.optional(),
 });
+// =============================================================================
+// BOARD VALIDATION SCHEMAS
+// =============================================================================
+export const BoardListSchema = z.object({
+    projectKey: z.string().trim().optional(),
+    type: z.string().trim().optional(),
+});
+export const BoardIssuesSchema = z.object({
+    jql: z.string().trim().optional(),
+    max: NumericStringSchema.optional(),
+});
+export const BoardRankSchema = z.object({
+    issues: z.array(z.string().trim().min(1)).min(1, 'At least one issue key is required'),
+    before: z.string().trim().optional(),
+    after: z.string().trim().optional(),
+}).refine(data => data.before || data.after, {
+    message: 'Either --before or --after must be specified',
+});
+// =============================================================================
+// SPRINT VALIDATION SCHEMAS
+// =============================================================================
+export const SprintListSchema = z.object({
+    state: z.enum(['future', 'active', 'closed']).optional(),
+});
+export const SprintCreateSchema = z.object({
+    name: z.string().trim().min(1, 'Sprint name is required'),
+    goal: z.string().trim().optional(),
+    start: z.string().trim().optional(),
+    end: z.string().trim().optional(),
+});
+export const SprintUpdateSchema = z.object({
+    name: z.string().trim().min(1).optional(),
+    goal: z.string().trim().optional(),
+    start: z.string().trim().optional(),
+    end: z.string().trim().optional(),
+}).refine(data => data.name || data.goal || data.start || data.end, {
+    message: 'At least one of --name, --goal, --start, or --end is required',
+});
+export const SprintIssuesSchema = z.object({
+    jql: z.string().trim().optional(),
+    max: NumericStringSchema.optional(),
+});
+export const SprintMoveSchema = z.object({
+    issues: z.array(z.string().trim().min(1)).min(1, 'At least one issue key is required'),
+    before: z.string().trim().optional(),
+    after: z.string().trim().optional(),
+});
+// =============================================================================
+// BACKLOG VALIDATION SCHEMAS
+// =============================================================================
+export const BacklogMoveSchema = z.object({
+    issues: z.array(z.string().trim().min(1)).min(1, 'At least one issue key is required'),
+});

package/package.json

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