jira-sprinter 1.0.1

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "jira-sprinter",
+  "version": "1.0.1",
+  "description": "Small CLI tool to manage sprints in JIRA Board",
+  "main": "src/main.ts",
+  "type": "commonjs",
+  "bin": "./dist/main.js",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "esbuild ./src/main.js --bundle --outdir=dist --platform=node --target=node20.0.0 --packages=bundle",
+    "format": "prettier --write '**/*.ts'",
+    "format-check": "prettier --check '**/*.ts'",
+    "test": "vitest run --coverage",
+    "update-snapshots": "vitest run --update",
+    "all": "yarn && yarn run build && yarn run format && yarn test"
+  },
+  "packageManager": "yarn@4.9.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redhat-plumbers-in-action/sprinter.git"
+  },
+  "author": "jamacku@redhat.com",
+  "license": "GPL-3.0+",
+  "bugs": {
+    "url": "https://github.com/redhat-plumbers-in-action/sprinter/issues"
+  },
+  "homepage": "https://github.com/redhat-plumbers-in-action/sprinter#readme",
+  "keywords": [
+    "cli",
+    "jira",
+    "agile",
+    "scrum"
+  ],
+  "dependencies": {
+    "@inquirer/checkbox": "^4.3.0",
+    "@inquirer/select": "4.4.0",
+    "@total-typescript/ts-reset": "0.6.1",
+    "chalk": "5.6.2",
+    "commander": "14.0.1",
+    "dotenv": "17.2.3",
+    "jira.js": "5.2.2",
+    "zod": "4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "24.7.2",
+    "@vitest/coverage-v8": "3.2.4",
+    "esbuild": "0.25.11",
+    "prettier": "3.6.2",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,233 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+import select, { Separator } from '@inquirer/select';
+import checkbox from '@inquirer/checkbox';
+
+import { Jira } from './jira';
+import { Logger } from './logger';
+import { getDefaultValue, getOptions, raise, tokenUnavailable } from './util';
+
+import { SearchResults } from 'jira.js/dist/esm/types/agile/models';
+import {
+  colorTaskSchema,
+  issueStatusSchema,
+  issueTypeSchema,
+  colorSizeSchema,
+  Size,
+} from './schema/jira';
+import { Issue } from 'jira.js/dist/esm/types/version2/models';
+
+export function cli(): Command {
+  const program = new Command();
+
+  program
+    .name('jira-sprinter')
+    .description('🏃 Small CLI tool to manage sprints in JIRA Board')
+    .version('1.0.0');
+
+  program
+    .option('-b, --board [board]', 'Jira Board ID', getDefaultValue('BOARD'))
+    .option(
+      '-a, --assignee [assignee]',
+      'Jira Assignee',
+      getDefaultValue('ASSIGNEE')
+    )
+    .option('-n, --nocolor', 'Disable color output', getDefaultValue('NOCOLOR'))
+    .option('-x, --dry', 'dry run', getDefaultValue('DRY'));
+
+  return program;
+}
+
+const runProgram = async () => {
+  const program = cli();
+  program.parse();
+
+  const options = getOptions(program.opts());
+  const logger = new Logger(!!options.nocolor);
+
+  const token = process.env.JIRA_API_TOKEN ?? tokenUnavailable();
+  const jira = new Jira(
+    'https://issues.redhat.com',
+    token,
+    options.dry,
+    logger
+  );
+
+  const version = await jira.getVersion();
+  console.debug(`JIRA Version: ${version}`);
+
+  const sprints = await jira.getSprints(+options.board);
+
+  const sprintOrBacklog = await select({
+    message: 'Pick issues to process from sprint or backlog',
+    choices: [
+      ...sprints.map(sprint => ({
+        name: `${sprint.name} (${sprint.state === 'active' ? chalk.green(sprint.state) : chalk.yellow(sprint.state)})`,
+        value: sprint.id,
+      })),
+      {
+        name: `${chalk.bold('Backlog')}`,
+        value: -1,
+      },
+    ],
+    default: -1,
+    pageSize: 5,
+    loop: false,
+  });
+
+  let issues: SearchResults['issues'] = [];
+  if (sprintOrBacklog === -1) {
+    issues = await jira.getBacklog(+options.board, options.assignee);
+  } else {
+    issues = await jira.getIssuesInSprint(sprintOrBacklog, options.assignee);
+  }
+
+  if (issues.length === 0) {
+    logger.log(`${chalk.green('No issues found')}.`);
+    process.exit(0);
+  }
+
+  // TODO:
+  // Show issue - allow to split it into tasks
+  // Allow to set story points and assignee
+  // add task into sprint
+
+  for (const issue of issues) {
+    logger.log(
+      `\n${issueTypeSchema.parse(issue.fields?.issuetype.name)} ${issue.key} - ${chalk.bold(issueStatusSchema.parse(issue.fields?.status.name))} - ${chalk.italic(issue.fields?.assignee?.displayName ?? '')}`
+    );
+    logger.log(
+      `${chalk.underline((issue.fields?.components ?? []).map(component => component.name).join(', ') || 'NO COMPONENT')} - ${chalk.italic(issue.fields?.summary ?? '')}`
+    );
+    logger.log(
+      `See more: ${chalk.italic.underline(jira.getIssueURL(issue.key ?? ''))}\n`
+    );
+
+    const availableTasks = [
+      { name: 'DEV Task', value: 39396, checked: true },
+      { name: 'QE Task', value: 39400, checked: true },
+      { name: 'Upstream', value: 39395 },
+      { name: 'Root Cause Analysis Task', value: 40950 },
+      { name: 'Preliminary Testing Task', value: 39398 },
+      { name: 'Integration Testing', value: 48270 },
+    ];
+
+    const answer = await checkbox({
+      message: `Split ${chalk.bold(issue.key)} into following tasks:\n`,
+      choices: [
+        ...availableTasks.map(task => ({
+          name: colorTaskSchema(task.name),
+          value: task.value,
+          checked: task.checked ?? false,
+        })),
+        new Separator(),
+        { name: 'SKIP', value: -1 },
+        { name: 'EXIT', value: -2 },
+      ],
+      loop: false,
+      pageSize: 10,
+    });
+
+    if (answer.includes(-1)) {
+      continue;
+    }
+
+    if (answer.includes(-2)) {
+      process.exit(0);
+    }
+
+    // Create tasks
+    await jira.createTasks(issue.key!, answer);
+
+    let tasks: Issue[] = [];
+    // wait for tasks to be created
+    for (let attempt = 1; attempt <= 10; attempt++) {
+      tasks = await jira.getlinkedTasks(
+        issue.key!,
+        answer.map(
+          task => availableTasks.find(t => t.value === task)?.name ?? ''
+        )
+      );
+
+      if (Array.isArray(tasks) && tasks.length >= answer.length) break;
+      if (attempt < 10) {
+        logger.log(`Waiting for tasks to be created...`);
+        await new Promise(resolve => setTimeout(resolve, 5000));
+      }
+    }
+
+    // loop through tasks and and set sprint, assignee and story points
+    for (const task of tasks) {
+      // Skip QE Task
+      if (task.fields.summary.includes('QE Task')) {
+        continue;
+      }
+
+      logger.log(`${chalk.italic(task.fields.summary)}`);
+      const storyPointsAnswer: Size = await select({
+        message: 'Story Points',
+        choices: [
+          {
+            name: colorSizeSchema.parse(0),
+            value: 0,
+          },
+          {
+            name: colorSizeSchema.parse(1),
+            value: 1,
+          },
+          {
+            name: colorSizeSchema.parse(2),
+            value: 2,
+          },
+          {
+            name: colorSizeSchema.parse(3),
+            value: 3,
+          },
+          {
+            name: colorSizeSchema.parse(5),
+            value: 5,
+          },
+          {
+            name: colorSizeSchema.parse(8),
+            value: 8,
+          },
+          {
+            name: colorSizeSchema.parse(13),
+            value: 13,
+          },
+        ],
+        default: issue.fields?.[jira.fields.storyPoints] ?? 3,
+        pageSize: 6,
+        loop: false,
+      });
+
+      const addToSprintAnswer = await select({
+        message: 'Add to sprint',
+        choices: [
+          { name: `${chalk.green('Yes')}`, value: true },
+          { name: `${chalk.red('No')}`, value: false },
+        ],
+        default: true,
+        pageSize: 2,
+        loop: false,
+      });
+
+      // update task
+      await jira.setValues(task.key, {
+        assignee: issue.fields?.assignee?.emailAddress,
+        size: storyPointsAnswer,
+        sprint:
+          addToSprintAnswer && sprintOrBacklog != -1
+            ? sprintOrBacklog
+            : undefined,
+      });
+    }
+
+    logger.log(
+      `Dropping ${chalk.bold(issue.key)} from sprint and setting story points to ${chalk.bold(0)}...`
+    );
+    await jira.setValues(issue.key!, { size: 0, sprint: null });
+  }
+};
+
+export default runProgram;

package/src/jira.ts

@@ -0,0 +1,179 @@
+import { AgileClient, Version2Client } from 'jira.js';
+import { SearchResults, Sprint } from 'jira.js/dist/esm/types/agile/models';
+
+import { raise } from './util';
+import { Size } from './schema/jira';
+import { Logger } from './logger';
+
+export class Jira {
+  readonly api: Version2Client;
+  readonly agile: AgileClient;
+  readonly fields = {
+    automation: 'customfield_12316240',
+    assignee: 'assignee',
+    priority: 'priority',
+    severity: 'customfield_12316142',
+    sprint: 'customfield_12310940',
+    storyPoints: 'customfield_12310243',
+  };
+
+  readonly issuesWithoutTasksJQL = `issueFunction not in linkedIssuesOf("type = Task AND (summary ~ 'DEV Task' OR summary ~ 'QE Task')") AND type not in (Task, Epic) AND project = "RHEL"`;
+
+  constructor(
+    readonly instance: string,
+    apiToken: string,
+    readonly dry: boolean,
+    readonly logger: Logger
+  ) {
+    this.api = new Version2Client({
+      host: instance,
+      authentication: {
+        oauth2: {
+          accessToken: apiToken,
+        },
+      },
+    });
+
+    this.agile = new AgileClient({
+      host: instance,
+      authentication: {
+        oauth2: {
+          accessToken: apiToken,
+        },
+      },
+    });
+  }
+
+  async getVersion(): Promise<string> {
+    const response = await this.api.serverInfo.getServerInfo();
+    return response.version ?? raise('Jira.getVersion(): missing version.');
+  }
+
+  async getSprints(boardId: number): Promise<Sprint[]> {
+    const response = await this.agile.board.getAllSprints({
+      boardId: boardId,
+      state: 'active,future',
+    });
+
+    return response.values;
+  }
+
+  async getIssuesInSprint(
+    sprintId: number,
+    assignee: string | undefined = undefined,
+    issuesWithoutTasks: boolean = true
+  ): Promise<SearchResults['issues']> {
+    let jql = assignee ? `assignee = "${assignee}"` : '';
+    jql += issuesWithoutTasks ? ` AND ${this.issuesWithoutTasksJQL}` : '';
+
+    const response = await this.agile.sprint.getIssuesForSprint({
+      sprintId: +sprintId,
+      jql,
+      maxResults: 500,
+      fields: [
+        'id',
+        'issuetype',
+        'status',
+        'summary',
+        'assignee',
+        'priority',
+        'components',
+        // sprint
+        this.fields.storyPoints,
+        this.fields.severity,
+      ],
+    });
+    return response.issues;
+  }
+
+  async getBacklog(
+    boardId: number,
+    assignee?: string
+  ): Promise<SearchResults['issues']> {
+    const response = await this.agile.board.getIssuesForBacklog({
+      boardId: boardId,
+      jql: assignee ? `assignee = "${assignee}"` : undefined,
+      maxResults: 500,
+      fields: [
+        'id',
+        'issuetype',
+        'status',
+        'summary',
+        'assignee',
+        'priority',
+        'components',
+        this.fields.storyPoints,
+        this.fields.severity,
+      ],
+    });
+
+    return response.issues;
+  }
+
+  composeTaskSummaryJQL(expectedTasks: string[]) {
+    return `summary ~ "\\\\[${expectedTasks.join('\\\\]: " OR summary ~ "\\\\[')}\\\\]: "`;
+  }
+
+  async getlinkedTasks(issue: string, expectedTasks: string[]) {
+    const response = await this.api.issueSearch.searchForIssuesUsingJqlPost({
+      jql: `issue in linkedIssues("${issue}") AND type = Task AND status = New AND (${this.composeTaskSummaryJQL(expectedTasks)})`,
+      fields: [
+        'id',
+        'issuetype',
+        'status',
+        'components',
+        'summary',
+        'assignee',
+        this.fields.storyPoints,
+      ],
+    });
+
+    return response.issues ?? [];
+  }
+
+  async createTasks(issue: string, tasks: number[]) {
+    if (this.dry) {
+      this.logger.log(
+        `Would create tasks: ${tasks.join(', ')} for issue: ${issue}`
+      );
+      return;
+    }
+
+    await this.api.issues.editIssue({
+      issueIdOrKey: issue,
+      fields: {
+        // Jira expects multi-select values as objects with id/value
+        [this.fields.automation]: tasks.map(id => ({ id: String(id) })),
+      },
+    });
+  }
+
+  async setValues(
+    issue: string,
+    values: {
+      assignee?: string;
+      size?: Size;
+      sprint?: number | null;
+    }
+  ) {
+    const assigneeValue = values.assignee
+      ? { [this.fields.assignee]: { name: values.assignee } }
+      : {};
+    const storyPointsValue = values.size
+      ? { [this.fields.storyPoints]: values.size }
+      : {};
+    const sprintValue =
+      values.sprint === undefined
+        ? {}
+        : { [this.fields.sprint]: values.sprint };
+
+    await this.api.issues.editIssue({
+      issueIdOrKey: issue,
+      fields: { ...assigneeValue, ...storyPointsValue, ...sprintValue },
+    });
+  }
+
+  getIssueURL(issue: string) {
+    return `${this.instance}/browse/${issue}`;
+  }
+}

package/src/logger.ts

@@ -0,0 +1,14 @@
+export class Logger {
+  static readonly colorRegex = /\[\d+m/gm;
+
+  constructor(readonly noColor: boolean = false) {}
+
+  log(message: string): void {
+    if (!this.noColor) {
+      console.log(message);
+      return;
+    }
+
+    console.log(message.replace(Logger.colorRegex, ''));
+  }
+}

package/src/main.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import os from 'os';
+import path from 'path';
+import dotenv from 'dotenv';
+
+import '@total-typescript/ts-reset';
+
+import runProgram from './cli';
+
+dotenv.config({
+  path: [
+    `${path.resolve(process.cwd(), '.env')}`,
+    `${path.resolve(os.homedir(), '.config', 'jira-sprinter', '.env')}`,
+    `${path.resolve(os.homedir(), '.env.jira-sprinter')}`,
+    `${path.resolve(os.homedir(), '.env')}`,
+  ],
+});
+
+try {
+  runProgram();
+} catch (error) {
+  console.error(error);
+  process.exit(1);
+}

package/src/schema/jira.ts

@@ -0,0 +1,107 @@
+import chalk from 'chalk';
+import { z } from 'zod';
+
+export const sizeSchema = z.union([
+  z.literal(0), // gray
+  z.literal(1), // green
+  z.literal(2), // green
+  z.literal(3), // yellow
+  z.literal(5), // yellow bold
+  z.literal(8), // red
+  z.literal(13), // red bold
+]);
+
+export const colorSizeSchema = sizeSchema.transform(val => {
+  switch (val) {
+    case 0:
+      return chalk.gray(val);
+    case 1:
+      return chalk.green(val);
+    case 2:
+      return chalk.green(val);
+    case 3:
+      return chalk.yellow(val);
+    case 5:
+      return chalk.yellow.bold(val);
+    case 8:
+      return chalk.red(val);
+    case 13:
+      return chalk.red.bold(val);
+    default:
+      return val;
+  }
+});
+
+export type Size = z.infer<typeof sizeSchema>;
+
+export const colorTaskSchema = (task: string) => {
+  switch (task) {
+    case 'DEV Task':
+      return chalk.green(task);
+    case 'Upstream':
+      return chalk.green(task);
+    case 'Root Cause Analysis Task':
+      return chalk.green(task);
+    case 'QE Task':
+      return chalk.yellow(task);
+    case 'Preliminary Testing Task':
+      return chalk.blue(task);
+    case 'Integration Testing':
+      return chalk.blue(task);
+    default:
+      return task;
+  }
+};
+
+export const issueIdSchema = z.string().regex(/^RHEL-\d+$/);
+
+export type IssueID = z.infer<typeof issueIdSchema>;
+
+export const issueTypeSchema = z
+  .union([
+    z.literal('Task'),
+    z.literal('Bug'),
+    z.literal('Story'),
+    z.literal('Epic'),
+    z.string(),
+  ])
+  .transform(val => {
+    switch (val) {
+      case 'Task':
+        return '☑️';
+      case 'Bug':
+        return '🐛';
+      case 'Story':
+        return '🎁';
+      case 'Epic':
+        return '⚡';
+      default:
+        return val;
+    }
+  });
+
+export const issueStatusSchema = z
+  .union([
+    z.literal('New'),
+    z.literal('Planning'),
+    z.literal('In Progress'),
+    z.literal('Integration'),
+    z.literal('Release Pending'),
+    z.string(),
+  ])
+  .transform(val => {
+    switch (val) {
+      case 'New':
+        return chalk.cyan(val);
+      case 'Planning':
+        return chalk.cyan(val);
+      case 'In Progress':
+        return chalk.blue(val);
+      case 'Integration':
+        return chalk.green(val);
+      case 'Release Pending':
+        return chalk.green(val);
+      default:
+        return val;
+    }
+  });

package/src/util.ts

@@ -0,0 +1,49 @@
+import { OptionValues } from 'commander';
+import os from 'os';
+
+export function raise(error: string): never {
+  throw new Error(error);
+}
+
+export function tokenUnavailable(): never {
+  return raise(
+    `JIRA_API_TOKEN not set.\nPlease set the JIRA_API_TOKEN environment variable in '~/.config/sprinter/.env' or '~/.env.sprinter' or '~/.env.'`
+  );
+}
+
+export function getUserFromLogin(): string {
+  const login = os.userInfo().username;
+  return `${login}@redhat.com`;
+}
+
+export function isDefaultValuesDisabled(): boolean {
+  return process.env['NODEFAULTS'] ? true : false;
+}
+
+export function getDefaultValue(
+  envName: 'ASSIGNEE' | 'BOARD' | 'NOCOLOR' | 'DRY'
+) {
+  if (isDefaultValuesDisabled()) {
+    return undefined;
+  }
+
+  const value = process.env[envName];
+
+  if (envName === 'ASSIGNEE' && !value) {
+    return getUserFromLogin();
+  }
+
+  if (envName === 'NOCOLOR' && !value) {
+    return false;
+  }
+
+  return value;
+}
+
+export function getOptions(inputs: OptionValues): OptionValues {
+  return {
+    ...inputs,
+    assignee: inputs.assignee || getDefaultValue('ASSIGNEE'),
+    board: inputs.board || getDefaultValue('BOARD'),
+  };
+}