jira-ai 0.9.98 → 0.9.99

package/dist/cli.js

@@ -26,6 +26,9 @@ 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();
@@ -459,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')
@@ -493,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/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}`;
     }

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