jira-ai 0.1.0

package/dist/lib/settings.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSettings = loadSettings;
+exports.isProjectAllowed = isProjectAllowed;
+exports.isCommandAllowed = isCommandAllowed;
+exports.getAllowedProjects = getAllowedProjects;
+exports.getAllowedCommands = getAllowedCommands;
+exports.__resetCache__ = __resetCache__;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+let cachedSettings = null;
+function loadSettings() {
+    if (cachedSettings) {
+        return cachedSettings;
+    }
+    const settingsPath = path_1.default.join(process.cwd(), 'settings.yaml');
+    if (!fs_1.default.existsSync(settingsPath)) {
+        console.warn('Warning: settings.yaml not found. Using default settings (all allowed).');
+        cachedSettings = {
+            projects: ['all'],
+            commands: ['all']
+        };
+        return cachedSettings;
+    }
+    try {
+        const fileContents = fs_1.default.readFileSync(settingsPath, 'utf8');
+        const settings = js_yaml_1.default.load(fileContents);
+        cachedSettings = {
+            projects: settings.projects || ['all'],
+            commands: settings.commands || ['all']
+        };
+        return cachedSettings;
+    }
+    catch (error) {
+        console.error('Error loading settings.yaml:', error);
+        process.exit(1);
+    }
+}
+function isProjectAllowed(projectKey) {
+    const settings = loadSettings();
+    if (settings.projects.includes('all')) {
+        return true;
+    }
+    return settings.projects.includes(projectKey);
+}
+function isCommandAllowed(commandName) {
+    const settings = loadSettings();
+    if (settings.commands.includes('all')) {
+        return true;
+    }
+    return settings.commands.includes(commandName);
+}
+function getAllowedProjects() {
+    const settings = loadSettings();
+    return settings.projects;
+}
+function getAllowedCommands() {
+    const settings = loadSettings();
+    return settings.commands;
+}
+// For testing purposes only
+function __resetCache__() {
+    cachedSettings = null;
+}

package/dist/lib/utils.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnvVars = validateEnvVars;
+exports.formatTimestamp = formatTimestamp;
+exports.truncate = truncate;
+exports.convertADFToMarkdown = convertADFToMarkdown;
+const chalk_1 = __importDefault(require("chalk"));
+const mdast_util_from_adf_1 = require("mdast-util-from-adf");
+const mdast_util_to_markdown_1 = require("mdast-util-to-markdown");
+/**
+ * Validate required environment variables
+ */
+function validateEnvVars() {
+    const required = [
+        'JIRA_HOST',
+        'JIRA_USER_EMAIL',
+        'JIRA_API_TOKEN',
+    ];
+    const missing = required.filter((key) => !process.env[key]);
+    if (missing.length > 0) {
+        console.error(chalk_1.default.red('✗ Missing required environment variables:\n'));
+        missing.forEach((key) => console.error(chalk_1.default.red(`  - ${key}`)));
+        console.log('\nPlease create a .env file with the following variables:');
+        console.log('  JIRA_HOST=https://your-domain.atlassian.net');
+        console.log('  JIRA_USER_EMAIL=your-email@example.com');
+        console.log('  JIRA_API_TOKEN=your-api-token');
+        console.log('\nGet your API token from: https://id.atlassian.com/manage-profile/security/api-tokens');
+        process.exit(1);
+    }
+}
+/**
+ * Format timestamp for display
+ */
+function formatTimestamp(date) {
+    const d = typeof date === 'string' ? new Date(date) : date;
+    return d.toLocaleString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+}
+/**
+ * Truncate text to max length with ellipsis
+ */
+function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.substring(0, maxLength - 3) + '...';
+}
+/**
+ * Convert Atlassian Document Format (ADF) to Markdown
+ * Handles both string content and ADF JSON objects
+ */
+function convertADFToMarkdown(content) {
+    // If content is already a string, return it as-is
+    if (typeof content === 'string') {
+        return content;
+    }
+    // If content is null or undefined, return empty string
+    if (!content) {
+        return '';
+    }
+    try {
+        // Convert ADF to mdast, then mdast to markdown
+        const mdastTree = (0, mdast_util_from_adf_1.fromADF)(content);
+        const markdown = (0, mdast_util_to_markdown_1.toMarkdown)(mdastTree);
+        return markdown.trim();
+    }
+    catch (error) {
+        // If conversion fails, fall back to JSON string representation
+        console.error('Failed to convert ADF to Markdown:', error);
+        return JSON.stringify(content, null, 2);
+    }
+}

package/jest.config.js

@@ -0,0 +1,21 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src', '<rootDir>/tests'],
+  testMatch: ['**/__tests__/**/*.ts', '**/*.test.ts', '**/*.spec.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/cli.ts'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  verbose: true,
+  moduleNameMapper: {
+    '^jira\\.js$': '<rootDir>/tests/__mocks__/jira.js.ts',
+    '^mdast-util-from-adf$': '<rootDir>/tests/__mocks__/mdast-util-from-adf.ts',
+    '^mdast-util-to-markdown$': '<rootDir>/tests/__mocks__/mdast-util-to-markdown.ts',
+    '^md-to-adf$': '<rootDir>/tests/__mocks__/md-to-adf.ts'
+  }
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "jira-ai",
+  "version": "0.1.0",
+  "description": "CLI tool for interacting with Atlassian Jira",
+  "main": "dist/cli.js",
+  "bin": {
+    "jira-ai": "./dist/cli.js"
+  },
+  "scripts": {
+    "dev": "ts-node src/cli.ts",
+    "build": "tsc && chmod +x dist/cli.js",
+    "start": "node dist/cli.js",
+    "link": "npm run build && npm link",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:verbose": "jest --verbose"
+  },
+  "keywords": [
+    "jira",
+    "cli",
+    "atlassian"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^11.0.0",
+    "dotenv": "^17.2.3",
+    "jira.js": "^5.2.2",
+    "js-yaml": "^4.1.1",
+    "md-to-adf": "^0.6.4",
+    "mdast-util-from-adf": "^2.2.0",
+    "mdast-util-to-markdown": "^2.1.2",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.0.3",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/settings.yaml

@@ -0,0 +1,24 @@
+# Jira AI Settings
+
+# Projects: List of allowed projects (use "all" to allow all projects)
+# Examples: BP, PM, PS
+projects:
+  - all
+  #- BP
+  #- PM
+  #- PS
+  # Uncomment below to allow all projects
+  # - all
+
+# Commands: List of allowed commands (use "all" to allow all commands)
+# Available commands: me, projects, task-with-details, project-statuses, run-jql, update-description, about
+commands:
+  - me
+  - projects
+  - run-jql
+  # Uncomment below to allow all commands
+  # - all
+  - task-with-details
+  # - project-statuses
+  - update-description
+  - add-comment

package/src/cli.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import dotenv from 'dotenv';
+import chalk from 'chalk';
+import { validateEnvVars } from './lib/utils';
+import { meCommand } from './commands/me';
+import { projectsCommand } from './commands/projects';
+import { taskWithDetailsCommand } from './commands/task-with-details';
+import { projectStatusesCommand } from './commands/project-statuses';
+import { runJqlCommand } from './commands/run-jql';
+import { updateDescriptionCommand } from './commands/update-description';
+import { addCommentCommand } from './commands/add-comment';
+import { aboutCommand } from './commands/about';
+import { isCommandAllowed, getAllowedCommands } from './lib/settings';
+
+// Load environment variables
+dotenv.config();
+
+// Validate environment variables
+validateEnvVars();
+
+// Helper function to wrap commands with permission check
+function withPermission(commandName: string, commandFn: (...args: any[]) => Promise<void>) {
+  return async (...args: any[]) => {
+    if (!isCommandAllowed(commandName)) {
+      console.error(chalk.red(`\n❌ Command '${commandName}' is not allowed.`));
+      console.log(chalk.gray('Allowed commands: ' + getAllowedCommands().join(', ')));
+      console.log(chalk.gray('Update settings.yaml to enable this command.\n'));
+      process.exit(1);
+    }
+    return commandFn(...args);
+  };
+}
+
+// Create CLI program
+const program = new Command();
+
+program
+  .name('jira-ai')
+  .description('CLI tool for interacting with Atlassian Jira')
+  .version('1.0.0');
+
+// Me command
+program
+  .command('me')
+  .description('Show basic user information')
+  .action(withPermission('me', meCommand));
+
+// Projects command
+program
+  .command('projects')
+  .description('Show list of projects')
+  .action(withPermission('projects', projectsCommand));
+
+// Task with details command
+program
+  .command('task-with-details <task-id>')
+  .description('Show task title, body, and comments')
+  .action(withPermission('task-with-details', taskWithDetailsCommand));
+
+// Project statuses command
+program
+  .command('project-statuses <project-id>')
+  .description('Show all possible statuses for a project')
+  .action(withPermission('project-statuses', projectStatusesCommand));
+
+// Run JQL command
+program
+  .command('run-jql <jql-query>')
+  .description('Execute JQL query and display results')
+  .option('-l, --limit <number>', 'Maximum number of results (default: 50)', '50')
+  .action(withPermission('run-jql', runJqlCommand));
+
+// Update description command
+program
+  .command('update-description <task-id>')
+  .description('Update task description from a Markdown file')
+  .requiredOption('--from-file <path>', 'Path to Markdown file')
+  .action(withPermission('update-description', updateDescriptionCommand));
+
+// Add comment command
+program
+  .command('add-comment')
+  .description('Add a comment to a Jira issue from a Markdown file')
+  .requiredOption('--file-path <path>', 'Path to Markdown file')
+  .requiredOption('--issue-key <key>', 'Jira issue key (e.g., PS-123)')
+  .action(withPermission('add-comment', addCommentCommand));
+
+// About command (always allowed)
+program
+  .command('about')
+  .description('Show information about available commands')
+  .action(aboutCommand);
+
+// Parse command line arguments
+program.parse();

package/src/commands/about.ts

@@ -0,0 +1,98 @@
+import chalk from 'chalk';
+import { getAllowedCommands, getAllowedProjects, isCommandAllowed } from '../lib/settings';
+
+interface CommandInfo {
+  name: string;
+  description: string;
+  usage: string;
+}
+
+const ALL_COMMANDS: CommandInfo[] = [
+  {
+    name: 'me',
+    description: 'Show details of current user',
+    usage: 'jira-ai me --help'
+  },
+  {
+    name: 'projects',
+    description: 'List available projects',
+    usage: 'jira-ai projects --help'
+  },
+  {
+    name: 'task-with-details',
+    description: 'Show task title, body, and comments',
+    usage: 'jira-ai task-with-details --help'
+  },
+  {
+    name: 'project-statuses',
+    description: 'Show all possible statuses for a project',
+    usage: 'jira-ai project-statuses --help'
+  },
+  {
+    name: 'run-jql',
+    description: 'Execute JQL query and display results',
+    usage: 'jira-ai run-jql "<jql-query>" [-l <limit>]'
+  },
+  {
+    name: 'update-description',
+    description: 'Update task description from a Markdown file',
+    usage: 'jira-ai update-description <task-id> --from-file <path>'
+  },
+  {
+    name: 'add-comment',
+    description: 'Add a comment to a Jira issue from a Markdown file',
+    usage: 'jira-ai add-comment --file-path <path> --issue-key <key>'
+  },
+  {
+    name: 'about',
+    description: 'Show this help message',
+    usage: 'jira-ai about'
+  }
+];
+
+export async function aboutCommand() {
+  console.log(chalk.bold.cyan('\n📋 Jira AI - Available Commands\n'));
+
+  console.log(chalk.bold('Usage:'));
+  console.log('  jira-ai <command> [options]\n');
+
+  const allowedCommandsList = getAllowedCommands();
+  const isAllAllowed = allowedCommandsList.includes('all');
+
+  // Filter commands based on settings (about is always shown)
+  const commandsToShow = ALL_COMMANDS.filter(cmd =>
+    cmd.name === 'about' || isAllAllowed || isCommandAllowed(cmd.name)
+  );
+
+  console.log(chalk.bold('Available Commands:\n'));
+
+  for (const cmd of commandsToShow) {
+    console.log(chalk.yellow(`  ${cmd.name}`));
+    console.log(`    ${cmd.description}`);
+    console.log(`    Usage: ${cmd.usage}\n`);
+  }
+
+  // Show disabled commands if not all are allowed
+  if (!isAllAllowed) {
+    const disabledCommands = ALL_COMMANDS.filter(cmd =>
+      cmd.name !== 'about' && !isCommandAllowed(cmd.name)
+    );
+
+    if (disabledCommands.length > 0) {
+      console.log(chalk.bold('Disabled Commands:\n'));
+      for (const cmd of disabledCommands) {
+        console.log(chalk.gray(`  ${cmd.name} - ${cmd.description}`));
+      }
+      console.log();
+    }
+  }
+
+  console.log(chalk.bold('For detailed help on any command, run:'));
+  console.log(chalk.green('  jira-ai <command> --help\n'));
+
+  console.log(chalk.bold('Configuration:'));
+  console.log('  Settings are managed in settings.yaml');
+  const allowedProjects = getAllowedProjects();
+  console.log(`  - Projects: ${allowedProjects.includes('all') ? 'All allowed' : allowedProjects.join(', ')}`);
+  console.log(`  - Commands: ${isAllAllowed ? 'All allowed' : allowedCommandsList.join(', ')}\n`);
+}

package/src/commands/add-comment.ts

@@ -0,0 +1,94 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import * as fs from 'fs';
+import * as path from 'path';
+import mdToAdf from 'md-to-adf';
+import { addIssueComment } from '../lib/jira-client';
+
+export async function addCommentCommand(
+  options: { filePath: string; issueKey: string }
+): Promise<void> {
+  const { filePath, issueKey } = options;
+
+  // Validate issueKey
+  if (!issueKey || issueKey.trim() === '') {
+    console.error(chalk.red('\nError: Issue key is required (use --issue-key)'));
+    process.exit(1);
+  }
+
+  // Validate file path
+  if (!filePath || filePath.trim() === '') {
+    console.error(chalk.red('\nError: File path is required (use --file-path)'));
+    process.exit(1);
+  }
+
+  // Resolve file path to absolute
+  const absolutePath = path.resolve(filePath);
+
+  // Check file exists
+  if (!fs.existsSync(absolutePath)) {
+    console.error(chalk.red(`\nError: File not found: ${absolutePath}`));
+    process.exit(1);
+  }
+
+  // Read file
+  let markdownContent: string;
+  try {
+    markdownContent = fs.readFileSync(absolutePath, 'utf-8');
+  } catch (error) {
+    console.error(
+      chalk.red(
+        '\nError reading file: ' +
+          (error instanceof Error ? error.message : 'Unknown error')
+      )
+    );
+    process.exit(1);
+  }
+
+  // Validate file is not empty
+  if (markdownContent.trim() === '') {
+    console.error(chalk.red('\nError: File is empty'));
+    process.exit(1);
+  }
+
+  // Convert Markdown to ADF
+  let adfContent: any;
+  try {
+    adfContent = mdToAdf(markdownContent);
+  } catch (error) {
+    console.error(
+      chalk.red(
+        '\nError converting Markdown to ADF: ' +
+          (error instanceof Error ? error.message : 'Unknown error')
+      )
+    );
+    process.exit(1);
+  }
+
+  // Add comment with spinner
+  const spinner = ora(`Adding comment to ${issueKey}...`).start();
+
+  try {
+    await addIssueComment(issueKey, adfContent);
+    spinner.succeed(chalk.green(`Comment added successfully to ${issueKey}`));
+    console.log(chalk.gray(`\nFile: ${absolutePath}`));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to add comment'));
+    console.error(
+      chalk.red(
+        '\nError: ' + (error instanceof Error ? error.message : 'Unknown error')
+      )
+    );
+
+    // Provide helpful hints based on error
+    if (error instanceof Error && error.message.includes('404')) {
+      console.log(chalk.yellow('\nHint: Check that the issue key is correct'));
+    } else if (error instanceof Error && error.message.includes('403')) {
+      console.log(
+        chalk.yellow('\nHint: You may not have permission to comment on this issue')
+      );
+    }
+
+    process.exit(1);
+  }
+}

package/src/commands/me.ts

@@ -0,0 +1,18 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { getCurrentUser } from '../lib/jira-client';
+import { formatUserInfo } from '../lib/formatters';
+
+export async function meCommand(): Promise<void> {
+  const spinner = ora('Fetching user information...').start();
+
+  try {
+    const user = await getCurrentUser();
+    spinner.succeed(chalk.green('User information retrieved'));
+    console.log(formatUserInfo(user));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to fetch user information'));
+    console.error(chalk.red('\nError: ' + (error instanceof Error ? error.message : 'Unknown error')));
+    process.exit(1);
+  }
+}

package/src/commands/project-statuses.ts

@@ -0,0 +1,18 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { getProjectStatuses } from '../lib/jira-client';
+import { formatProjectStatuses } from '../lib/formatters';
+
+export async function projectStatusesCommand(projectId: string): Promise<void> {
+  const spinner = ora(`Fetching statuses for project ${projectId}...`).start();
+
+  try {
+    const statuses = await getProjectStatuses(projectId);
+    spinner.succeed(chalk.green('Project statuses retrieved'));
+    console.log(formatProjectStatuses(projectId, statuses));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to fetch project statuses'));
+    console.error(chalk.red('\nError: ' + (error instanceof Error ? error.message : 'Unknown error')));
+    process.exit(1);
+  }
+}

package/src/commands/projects.ts

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { getProjects } from '../lib/jira-client';
+import { formatProjects } from '../lib/formatters';
+import { getAllowedProjects, isProjectAllowed } from '../lib/settings';
+
+export async function projectsCommand(): Promise<void> {
+  const spinner = ora('Fetching projects...').start();
+
+  try {
+    const allProjects = await getProjects();
+    const allowedProjectKeys = getAllowedProjects();
+
+    // Filter projects based on settings
+    const filteredProjects = allowedProjectKeys.includes('all')
+      ? allProjects
+      : allProjects.filter(project => isProjectAllowed(project.key));
+
+    spinner.succeed(chalk.green('Projects retrieved'));
+
+    if (filteredProjects.length === 0) {
+      console.log(chalk.yellow('\nNo projects match your settings configuration.'));
+      console.log(chalk.gray('Allowed projects: ' + allowedProjectKeys.join(', ')));
+    } else {
+      console.log(formatProjects(filteredProjects));
+    }
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to fetch projects'));
+    console.error(chalk.red('\nError: ' + (error instanceof Error ? error.message : 'Unknown error')));
+    process.exit(1);
+  }
+}

package/src/commands/run-jql.ts

@@ -0,0 +1,40 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { searchIssuesByJql } from '../lib/jira-client';
+import { formatJqlResults } from '../lib/formatters';
+
+export async function runJqlCommand(jqlQuery: string, options: { limit: string }): Promise<void> {
+  // Validate JQL query is not empty
+  if (!jqlQuery || jqlQuery.trim() === '') {
+    console.error(chalk.red('\nError: JQL query cannot be empty'));
+    process.exit(1);
+  }
+
+  // Parse and validate limit parameter
+  let maxResults = 50; // default
+  if (options.limit) {
+    const parsedLimit = parseInt(options.limit, 10);
+    if (isNaN(parsedLimit) || parsedLimit < 1) {
+      console.error(chalk.red('\nError: Limit must be a positive number'));
+      process.exit(1);
+    }
+    if (parsedLimit > 1000) {
+      console.warn(chalk.yellow('\nWarning: Limit is very high. Using 1000 as maximum.'));
+      maxResults = 1000;
+    } else {
+      maxResults = parsedLimit;
+    }
+  }
+
+  const spinner = ora('Executing JQL query...').start();
+
+  try {
+    const issues = await searchIssuesByJql(jqlQuery, maxResults);
+    spinner.succeed(chalk.green('Query executed successfully'));
+    console.log(formatJqlResults(issues));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to execute JQL query'));
+    console.error(chalk.red('\nError: ' + (error instanceof Error ? error.message : 'Unknown error')));
+    process.exit(1);
+  }
+}

package/src/commands/task-with-details.ts

@@ -0,0 +1,18 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { getTaskWithDetails } from '../lib/jira-client';
+import { formatTaskDetails } from '../lib/formatters';
+
+export async function taskWithDetailsCommand(taskId: string): Promise<void> {
+  const spinner = ora(`Fetching details for ${taskId}...`).start();
+
+  try {
+    const task = await getTaskWithDetails(taskId);
+    spinner.succeed(chalk.green('Task details retrieved'));
+    console.log(formatTaskDetails(task));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to fetch task details'));
+    console.error(chalk.red('\nError: ' + (error instanceof Error ? error.message : 'Unknown error')));
+    process.exit(1);
+  }
+}