jira-ai 0.1.0

package/README.md

@@ -0,0 +1,364 @@
+# Jira AI
+
+A TypeScript-based command-line interface for interacting with Atlassian Jira. Built with jira.js library and featuring beautiful terminal output with tables and colors.
+
+## Features
+
+- View your user information
+- List all projects
+- View task details with comments
+- Show available statuses for a project
+- Update issue descriptions from Markdown files
+- Execute JQL queries with formatted results
+- Beautiful table formatting with cli-table3
+- Colored output for better readability
+- Loading spinners for async operations
+
+## Prerequisites
+
+- Node.js (v14 or higher)
+- npm or yarn
+- Jira account with API access
+
+## Installation
+
+1. Clone or navigate to the project directory:
+```bash
+cd /home/manager/jira-service
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+4. Install globally:
+```bash
+sudo npm link
+```
+
+After installation, you can use the `jira-ai` command from anywhere in your terminal.
+
+## Configuration
+
+Create a `.env` file in the project root with your Jira credentials:
+
+```env
+JIRA_HOST=https://your-domain.atlassian.net
+JIRA_USER_EMAIL=your-email@example.com
+JIRA_API_TOKEN=your-api-token
+```
+
+### Getting Your API Token
+
+1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click "Create API token"
+3. Give it a label and copy the generated token
+4. Add the token to your `.env` file
+
+## Available Commands
+
+### Show User Information
+
+Display your basic Jira user information including host, display name, email, account ID, status, and timezone.
+
+```bash
+jira-ai me
+```
+
+**Output:**
+```
+User Information:
+┌────────────────────┬──────────────────────────────────────────────────┐
+│ Property           │ Value                                            │
+├────────────────────┼──────────────────────────────────────────────────┤
+│ Host               │ https://your-domain.atlassian.net                │
+├────────────────────┼──────────────────────────────────────────────────┤
+│ Display Name       │ Your Name                                        │
+├────────────────────┼──────────────────────────────────────────────────┤
+│ Email              │ your-email@example.com                           │
+├────────────────────┼──────────────────────────────────────────────────┤
+│ Account ID         │ 557058:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx         │
+├────────────────────┼──────────────────────────────────────────────────┤
+│ Status             │ Active                                           │
+├────────────────────┼──────────────────────────────────────────────────┤
+│ Time Zone          │ Europe/Kiev                                      │
+└────────────────────┴──────────────────────────────────────────────────┘
+```
+
+### List Projects
+
+Show all projects you have access to in a formatted table.
+
+```bash
+jira-ai projects
+```
+
+**Output:**
+```
+Projects (25 total)
+
+┌────────────┬───────────────────────────────────┬───────────────┬─────────────────────────┐
+│ Key        │ Name                              │ Type          │ Lead                    │
+├────────────┼───────────────────────────────────┼───────────────┼─────────────────────────┤
+│ BP         │ BookingPal                        │ software      │ Pavel Boiko             │
+├────────────┼───────────────────────────────────┼───────────────┼─────────────────────────┤
+│ IT         │ IT Support                        │ software      │ Anatolii Fesiuk         │
+└────────────┴───────────────────────────────────┴───────────────┴─────────────────────────┘
+```
+
+### View Task Details
+
+Display detailed information about a specific task including title, status, assignee, reporter, description, and all comments.
+
+```bash
+jira-ai task-with-details <task-id>
+```
+
+**Example:**
+```bash
+jira-ai task-with-details BP-1234
+```
+
+**Output:**
+```
+BP-1234: Configure new production server
+
+┌───────────────┬─────────────────────────────────────────────────────────────────┐
+│ Property      │ Value                                                           │
+├───────────────┼─────────────────────────────────────────────────────────────────┤
+│ Status        │ In Progress                                                     │
+├───────────────┼─────────────────────────────────────────────────────────────────┤
+│ Assignee      │ John Doe                                                        │
+├───────────────┼─────────────────────────────────────────────────────────────────┤
+│ Reporter      │ Jane Smith                                                      │
+├───────────────┼─────────────────────────────────────────────────────────────────┤
+│ Created       │ Jan 10, 2026, 02:30 PM                                          │
+├───────────────┼─────────────────────────────────────────────────────────────────┤
+│ Updated       │ Jan 10, 2026, 04:15 PM                                          │
+└───────────────┴─────────────────────────────────────────────────────────────────┘
+
+Description:
+────────────────────────────────────────────────────────────────────────────────
+We need to configure the production server...
+────────────────────────────────────────────────────────────────────────────────
+
+Comments (2):
+
+1. John Doe - Jan 10, 2026, 03:00 PM
+────────────────────────────────────────────────────────────────────────────────
+Started working on this task...
+────────────────────────────────────────────────────────────────────────────────
+```
+
+### Show Project Statuses
+
+Display all possible issue statuses available in a specific project.
+
+```bash
+jira-ai project-statuses <project-id>
+```
+
+**Example:**
+```bash
+jira-ai project-statuses BP
+```
+
+**Output:**
+```
+Project BP - Available Statuses (21 total)
+
+┌─────────────────────────┬────────────────────┬─────────────────────────────────────────────┐
+│ Status Name             │ Category           │ Description                                 │
+├─────────────────────────┼────────────────────┼─────────────────────────────────────────────┤
+│ Open                    │ To Do              │ The work item is open and ready for work    │
+├─────────────────────────┼────────────────────┼─────────────────────────────────────────────┤
+│ In Progress             │ In Progress        │ This work item is being actively worked on  │
+├─────────────────────────┼────────────────────┼─────────────────────────────────────────────┤
+│ Closed                  │ Done               │ The work item is considered finished        │
+└─────────────────────────┴────────────────────┴─────────────────────────────────────────────┘
+```
+
+### Execute JQL Query
+
+Run a JQL (Jira Query Language) query and display results in a formatted table.
+
+```bash
+jira-ai run-jql <jql-query> [--limit <number>]
+```
+
+**Example:**
+```bash
+jira-ai run-jql "project = BP AND status = 'In Progress'" --limit 10
+```
+
+**Output:**
+```
+JQL Query Results (5 issues found)
+
+┌────────────┬──────────────────────────┬─────────────┬────────────┬──────────┐
+│ Key        │ Summary                  │ Status      │ Assignee   │ Priority │
+├────────────┼──────────────────────────┼─────────────┼────────────┼──────────┤
+│ BP-1234    │ Configure production...  │ In Progress │ John Doe   │ High     │
+├────────────┼──────────────────────────┼─────────────┼────────────┼──────────┤
+│ BP-5678    │ Update documentation     │ In Progress │ Jane Smith │ Medium   │
+└────────────┴──────────────────────────┴─────────────┴────────────┴──────────┘
+```
+
+### Update Issue Description
+
+Update a Jira issue's description from a Markdown file. The Markdown content is automatically converted to Atlassian Document Format (ADF).
+
+```bash
+jira-ai update-description <task-id> --from-file <path-to-markdown-file>
+```
+
+**Example:**
+```bash
+jira-ai update-description BP-1234 --from-file ./description.md
+```
+
+**Requirements:**
+- The command must be enabled in `settings.yaml` (commented out by default for safety)
+- You must have edit permissions for the issue in Jira
+- The Markdown file must exist and be non-empty
+
+**Supported Markdown:**
+- Headings (# H1, ## H2, etc.)
+- Bold, italic, strikethrough
+- Lists (ordered and unordered)
+- Code blocks with syntax highlighting
+- Links and images
+- Tables
+- Blockquotes
+
+**Output:**
+```
+✔ Description updated successfully for BP-1234
+
+File: /path/to/description.md
+```
+
+**Note:** This command replaces the entire issue description with the content from the file.
+
+## Settings
+
+The CLI uses a `settings.yaml` file to control which commands and projects are allowed. This provides an additional security layer.
+
+**Example settings.yaml:**
+```yaml
+# Projects: List of allowed projects (use "all" to allow all projects)
+projects:
+  - all
+
+# Commands: List of allowed commands (use "all" to allow all commands)
+commands:
+  - me
+  - projects
+  - run-jql
+  - task-with-details
+  # - update-description  # Uncomment to enable description updates
+  # - project-statuses
+```
+
+**Important:** The `update-description` command is commented out by default since it's a WRITE operation. Uncomment it only if you need to update issue descriptions.
+
+## Development
+
+### Scripts
+
+- `npm run dev` - Run in development mode with ts-node
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm start` - Run the compiled version
+- `npm run link` - Build and install globally
+
+### Project Structure
+
+```
+jira-service/
+├── src/
+│   ├── cli.ts                       # Main entry point
+│   ├── commands/                    # Command implementations
+│   │   ├── about.ts
+│   │   ├── me.ts
+│   │   ├── projects.ts
+│   │   ├── project-statuses.ts
+│   │   ├── run-jql.ts
+│   │   ├── task-with-details.ts
+│   │   └── update-description.ts    # Update issue descriptions
+│   ├── lib/
+│   │   ├── jira-client.ts           # Jira API wrapper
+│   │   ├── formatters.ts            # Output formatting
+│   │   ├── settings.ts              # Settings management
+│   │   └── utils.ts                 # Utility functions
+│   └── types/
+│       └── md-to-adf.d.ts           # Type definitions for md-to-adf
+├── tests/                           # Test files
+│   ├── __mocks__/                   # Jest mocks
+│   ├── cli-permissions.test.ts
+│   ├── projects.test.ts
+│   ├── settings.test.ts
+│   └── update-description.test.ts
+├── dist/                            # Compiled JavaScript
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+├── settings.yaml                    # Command/project permissions
+└── .env                             # Environment variables
+```
+
+## Technologies Used
+
+- **TypeScript** - Type-safe JavaScript
+- **jira.js** - Jira API client library
+- **Commander.js** - CLI framework
+- **cli-table3** - Beautiful terminal tables
+- **chalk** - Terminal colors and styling
+- **ora** - Loading spinners
+- **dotenv** - Environment variable management
+- **md-to-adf** - Markdown to Atlassian Document Format conversion
+- **Jest** - Testing framework
+
+## Error Handling
+
+The CLI provides helpful error messages:
+
+- Missing environment variables with instructions
+- API errors with detailed messages
+- Invalid task IDs or project keys
+- Network connectivity issues
+
+## Troubleshooting
+
+### Command not found after installation
+
+Make sure you ran `sudo npm link` and that your npm global bin directory is in your PATH.
+
+### Authentication errors
+
+Verify your `.env` file has the correct:
+- JIRA_HOST (with https://)
+- JIRA_USER_EMAIL
+- JIRA_API_TOKEN
+
+Regenerate your API token if needed.
+
+### Permission denied
+
+If you get permission errors, make sure the CLI is executable:
+```bash
+chmod +x dist/cli.js
+```
+
+## License
+
+ISC
+
+## Contributing
+
+Feel free to submit issues and enhancement requests.

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const dotenv_1 = __importDefault(require("dotenv"));
+const chalk_1 = __importDefault(require("chalk"));
+const utils_1 = require("./lib/utils");
+const me_1 = require("./commands/me");
+const projects_1 = require("./commands/projects");
+const task_with_details_1 = require("./commands/task-with-details");
+const project_statuses_1 = require("./commands/project-statuses");
+const run_jql_1 = require("./commands/run-jql");
+const update_description_1 = require("./commands/update-description");
+const add_comment_1 = require("./commands/add-comment");
+const about_1 = require("./commands/about");
+const settings_1 = require("./lib/settings");
+// Load environment variables
+dotenv_1.default.config();
+// Validate environment variables
+(0, utils_1.validateEnvVars)();
+// Helper function to wrap commands with permission check
+function withPermission(commandName, commandFn) {
+    return async (...args) => {
+        if (!(0, settings_1.isCommandAllowed)(commandName)) {
+            console.error(chalk_1.default.red(`\n❌ Command '${commandName}' is not allowed.`));
+            console.log(chalk_1.default.gray('Allowed commands: ' + (0, settings_1.getAllowedCommands)().join(', ')));
+            console.log(chalk_1.default.gray('Update settings.yaml to enable this command.\n'));
+            process.exit(1);
+        }
+        return commandFn(...args);
+    };
+}
+// Create CLI program
+const program = new commander_1.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', me_1.meCommand));
+// Projects command
+program
+    .command('projects')
+    .description('Show list of projects')
+    .action(withPermission('projects', projects_1.projectsCommand));
+// Task with details command
+program
+    .command('task-with-details <task-id>')
+    .description('Show task title, body, and comments')
+    .action(withPermission('task-with-details', task_with_details_1.taskWithDetailsCommand));
+// Project statuses command
+program
+    .command('project-statuses <project-id>')
+    .description('Show all possible statuses for a project')
+    .action(withPermission('project-statuses', project_statuses_1.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', run_jql_1.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', update_description_1.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', add_comment_1.addCommentCommand));
+// About command (always allowed)
+program
+    .command('about')
+    .description('Show information about available commands')
+    .action(about_1.aboutCommand);
+// Parse command line arguments
+program.parse();

package/dist/commands/about.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aboutCommand = aboutCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const settings_1 = require("../lib/settings");
+const ALL_COMMANDS = [
+    {
+        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'
+    }
+];
+async function aboutCommand() {
+    console.log(chalk_1.default.bold.cyan('\n📋 Jira AI - Available Commands\n'));
+    console.log(chalk_1.default.bold('Usage:'));
+    console.log('  jira-ai <command> [options]\n');
+    const allowedCommandsList = (0, settings_1.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 || (0, settings_1.isCommandAllowed)(cmd.name));
+    console.log(chalk_1.default.bold('Available Commands:\n'));
+    for (const cmd of commandsToShow) {
+        console.log(chalk_1.default.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' && !(0, settings_1.isCommandAllowed)(cmd.name));
+        if (disabledCommands.length > 0) {
+            console.log(chalk_1.default.bold('Disabled Commands:\n'));
+            for (const cmd of disabledCommands) {
+                console.log(chalk_1.default.gray(`  ${cmd.name} - ${cmd.description}`));
+            }
+            console.log();
+        }
+    }
+    console.log(chalk_1.default.bold('For detailed help on any command, run:'));
+    console.log(chalk_1.default.green('  jira-ai <command> --help\n'));
+    console.log(chalk_1.default.bold('Configuration:'));
+    console.log('  Settings are managed in settings.yaml');
+    const allowedProjects = (0, settings_1.getAllowedProjects)();
+    console.log(`  - Projects: ${allowedProjects.includes('all') ? 'All allowed' : allowedProjects.join(', ')}`);
+    console.log(`  - Commands: ${isAllAllowed ? 'All allowed' : allowedCommandsList.join(', ')}\n`);
+}

package/dist/commands/add-comment.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addCommentCommand = addCommentCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const md_to_adf_1 = __importDefault(require("md-to-adf"));
+const jira_client_1 = require("../lib/jira-client");
+async function addCommentCommand(options) {
+    const { filePath, issueKey } = options;
+    // Validate issueKey
+    if (!issueKey || issueKey.trim() === '') {
+        console.error(chalk_1.default.red('\nError: Issue key is required (use --issue-key)'));
+        process.exit(1);
+    }
+    // Validate file path
+    if (!filePath || filePath.trim() === '') {
+        console.error(chalk_1.default.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_1.default.red(`\nError: File not found: ${absolutePath}`));
+        process.exit(1);
+    }
+    // Read file
+    let markdownContent;
+    try {
+        markdownContent = fs.readFileSync(absolutePath, 'utf-8');
+    }
+    catch (error) {
+        console.error(chalk_1.default.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_1.default.red('\nError: File is empty'));
+        process.exit(1);
+    }
+    // Convert Markdown to ADF
+    let adfContent;
+    try {
+        adfContent = (0, md_to_adf_1.default)(markdownContent);
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('\nError converting Markdown to ADF: ' +
+            (error instanceof Error ? error.message : 'Unknown error')));
+        process.exit(1);
+    }
+    // Add comment with spinner
+    const spinner = (0, ora_1.default)(`Adding comment to ${issueKey}...`).start();
+    try {
+        await (0, jira_client_1.addIssueComment)(issueKey, adfContent);
+        spinner.succeed(chalk_1.default.green(`Comment added successfully to ${issueKey}`));
+        console.log(chalk_1.default.gray(`\nFile: ${absolutePath}`));
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red('Failed to add comment'));
+        console.error(chalk_1.default.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_1.default.yellow('\nHint: Check that the issue key is correct'));
+        }
+        else if (error instanceof Error && error.message.includes('403')) {
+            console.log(chalk_1.default.yellow('\nHint: You may not have permission to comment on this issue'));
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/me.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meCommand = meCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const jira_client_1 = require("../lib/jira-client");
+const formatters_1 = require("../lib/formatters");
+async function meCommand() {
+    const spinner = (0, ora_1.default)('Fetching user information...').start();
+    try {
+        const user = await (0, jira_client_1.getCurrentUser)();
+        spinner.succeed(chalk_1.default.green('User information retrieved'));
+        console.log((0, formatters_1.formatUserInfo)(user));
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red('Failed to fetch user information'));
+        console.error(chalk_1.default.red('\nError: ' + (error instanceof Error ? error.message : 'Unknown error')));
+        process.exit(1);
+    }
+}