jira-ai 0.1.0

package/src/lib/utils.ts

@@ -0,0 +1,76 @@
+import chalk from 'chalk';
+import { fromADF } from 'mdast-util-from-adf';
+import { toMarkdown } from 'mdast-util-to-markdown';
+
+/**
+ * Validate required environment variables
+ */
+export function validateEnvVars(): void {
+  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.red('✗ Missing required environment variables:\n'));
+    missing.forEach((key) => console.error(chalk.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
+ */
+export function formatTimestamp(date: string | Date): string {
+  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
+ */
+export function truncate(text: string, maxLength: number): string {
+  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
+ */
+export function convertADFToMarkdown(content: any): string {
+  // 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 = fromADF(content);
+    const markdown = 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/src/types/md-to-adf.d.ts

@@ -0,0 +1,14 @@
+declare module 'md-to-adf' {
+  /**
+   * Convert Markdown to Atlassian Document Format (ADF)
+   * @param markdown - GitHub Flavored Markdown text
+   * @returns ADF document object
+   */
+  function mdToAdf(markdown: string): {
+    version: number;
+    type: string;
+    content: any[];
+  };
+
+  export = mdToAdf;
+}

package/tests/README.md

@@ -0,0 +1,97 @@
+# Test Suite Documentation
+
+## Overview
+
+This test suite provides comprehensive coverage for the Jira AI settings and permissions system.
+
+## Test Files
+
+### 1. `settings.test.ts` (16 tests)
+Tests the core settings module functionality:
+- **Loading settings**: Reading and parsing settings.yaml
+- **Project filtering**: Testing project allow/deny lists
+- **Command filtering**: Testing command permissions
+- **Caching**: Ensuring settings are cached properly
+- **Error handling**: Invalid YAML, missing files
+
+**Coverage**: 100% of settings.ts module
+
+### 2. `projects.test.ts` (6 tests)
+Tests the projects command with filtering:
+- Displaying all projects when "all" is allowed
+- Filtering projects based on settings.yaml
+- Handling empty results
+- API error handling
+
+**Coverage**: 100% of projects.ts command
+
+### 3. `cli-permissions.test.ts` (9 tests)
+Tests the CLI permission wrapper:
+- Command allow/deny logic
+- Permission enforcement at CLI level
+- Error messages for blocked commands
+- Integration scenarios
+
+**Total: 31 tests passing**
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests with verbose output
+npm run test:verbose
+```
+
+## Test Coverage
+
+Current coverage for tested modules:
+- `src/lib/settings.ts`: 100%
+- `src/commands/projects.ts`: 100%
+
+## Key Test Scenarios Covered
+
+### Settings Module
+✓ Load settings from YAML file
+✓ Default to "all" when file doesn't exist
+✓ Handle null/undefined values
+✓ Exit on invalid YAML
+✓ Project allow/deny filtering
+✓ Command allow/deny filtering
+✓ Case-sensitive project matching
+✓ Settings caching
+
+### Projects Command
+✓ Show all projects when "all" allowed
+✓ Filter to specific projects (BP, PM, PS)
+✓ Show warning for no matches
+✓ Handle API errors gracefully
+
+### CLI Permissions
+✓ Allow/deny command execution
+✓ Display helpful error messages
+✓ Support "all" wildcard
+✓ Pass arguments to allowed commands
+
+## Mock Strategy
+
+The test suite uses Jest mocks for:
+- **fs module**: Mocked to test file I/O without actual files
+- **jira.js**: Mocked to avoid ES module issues
+- **ora, chalk**: Mocked to test CLI output
+- **console**: Spied to verify error/warning messages
+
+## Future Test Coverage
+
+Potential areas to expand testing:
+- Other command modules (me, task-with-details, project-statuses)
+- Formatters
+- Jira client integration tests
+- End-to-end CLI tests

package/tests/__mocks__/jira.js.ts

@@ -0,0 +1,4 @@
+// Mock for jira.js library to avoid ES module issues in tests
+export class Version3Client {
+  constructor() {}
+}

package/tests/__mocks__/md-to-adf.ts

@@ -0,0 +1,7 @@
+const mdToAdf = jest.fn((markdown: string) => ({
+  version: 1,
+  type: 'doc',
+  content: []
+}));
+
+export default mdToAdf;

package/tests/__mocks__/mdast-util-from-adf.ts

@@ -0,0 +1,4 @@
+export const fromADF = jest.fn((adf: any) => ({
+  type: 'root',
+  children: []
+}));

package/tests/__mocks__/mdast-util-to-markdown.ts

@@ -0,0 +1 @@
+export const toMarkdown = jest.fn((tree: any) => 'Mocked markdown content');

package/tests/add-comment.test.ts

@@ -0,0 +1,226 @@
+import { addCommentCommand } from '../src/commands/add-comment';
+import * as jiraClient from '../src/lib/jira-client';
+import * as fs from 'fs';
+import * as path from 'path';
+import mdToAdf from 'md-to-adf';
+
+// Mock dependencies
+jest.mock('fs');
+jest.mock('md-to-adf');
+jest.mock('../src/lib/jira-client');
+jest.mock('../src/lib/utils');
+jest.mock('ora', () => {
+  return jest.fn(() => ({
+    start: jest.fn().mockReturnThis(),
+    succeed: jest.fn().mockReturnThis(),
+    fail: jest.fn().mockReturnThis()
+  }));
+});
+
+const mockJiraClient = jiraClient as jest.Mocked<typeof jiraClient>;
+const mockFs = fs as jest.Mocked<typeof fs>;
+const mockMdToAdf = mdToAdf as jest.MockedFunction<typeof mdToAdf>;
+
+describe('Add Comment Command', () => {
+  const mockIssueKey = 'TEST-123';
+  const mockFilePath = '/path/to/comment.md';
+  const mockMarkdownContent = '# Test Comment\n\nThis is a test comment.';
+  const mockAdfContent = {
+    version: 1,
+    type: 'doc',
+    content: [
+      {
+        type: 'heading',
+        attrs: { level: 1 },
+        content: [{ type: 'text', text: 'Test Comment' }]
+      }
+    ]
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    console.log = jest.fn();
+    console.error = jest.fn();
+
+    // Setup default mocks
+    jest.spyOn(mockFs, 'existsSync').mockReturnValue(true);
+    jest.spyOn(mockFs, 'readFileSync').mockReturnValue(mockMarkdownContent);
+    mockMdToAdf.mockReturnValue(mockAdfContent);
+    mockJiraClient.addIssueComment = jest.fn().mockResolvedValue(undefined);
+  });
+
+  it('should successfully add a comment to a Jira issue', async () => {
+    await addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey });
+
+    expect(mockFs.existsSync).toHaveBeenCalledWith(path.resolve(mockFilePath));
+    expect(mockFs.readFileSync).toHaveBeenCalledWith(path.resolve(mockFilePath), 'utf-8');
+    expect(mockMdToAdf).toHaveBeenCalledWith(mockMarkdownContent);
+    expect(mockJiraClient.addIssueComment).toHaveBeenCalledWith(
+      mockIssueKey,
+      mockAdfContent
+    );
+    expect(console.log).toHaveBeenCalled();
+  });
+
+  it('should exit with error when issue key is empty', async () => {
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(addCommentCommand({ filePath: mockFilePath, issueKey: '' })).rejects.toThrow(
+      'Process exit'
+    );
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Issue key is required')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error when file path is empty', async () => {
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(addCommentCommand({ filePath: '', issueKey: mockIssueKey })).rejects.toThrow(
+      'Process exit'
+    );
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('File path is required')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error when file does not exist', async () => {
+    jest.spyOn(mockFs, 'existsSync').mockReturnValue(false);
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(
+      addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey })
+    ).rejects.toThrow('Process exit');
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('File not found')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error when file read fails', async () => {
+    const readError = new Error('Permission denied');
+    jest.spyOn(mockFs, 'readFileSync').mockImplementation(() => {
+      throw readError;
+    });
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(
+      addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey })
+    ).rejects.toThrow('Process exit');
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Error reading file')
+    );
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Permission denied')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error when file is empty', async () => {
+    jest.spyOn(mockFs, 'readFileSync').mockReturnValue('   \n  \t  ');
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(
+      addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey })
+    ).rejects.toThrow('Process exit');
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('File is empty')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error when markdown conversion fails', async () => {
+    const conversionError = new Error('Invalid markdown syntax');
+    mockMdToAdf.mockImplementation(() => {
+      throw conversionError;
+    });
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(
+      addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey })
+    ).rejects.toThrow('Process exit');
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Error converting Markdown to ADF')
+    );
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid markdown syntax')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error and hint when issue not found (404)', async () => {
+    const apiError = new Error('Issue not found (404)');
+    mockJiraClient.addIssueComment = jest.fn().mockRejectedValue(apiError);
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(
+      addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey })
+    ).rejects.toThrow('Process exit');
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Issue not found (404)')
+    );
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining('Check that the issue key is correct')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+
+  it('should exit with error and hint when permission denied (403)', async () => {
+    const apiError = new Error('Permission denied (403)');
+    mockJiraClient.addIssueComment = jest.fn().mockRejectedValue(apiError);
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit');
+    });
+
+    await expect(
+      addCommentCommand({ filePath: mockFilePath, issueKey: mockIssueKey })
+    ).rejects.toThrow('Process exit');
+
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringContaining('Permission denied (403)')
+    );
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining('You may not have permission to comment on this issue')
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    processExitSpy.mockRestore();
+  });
+});

package/tests/cli-permissions.test.ts

@@ -0,0 +1,156 @@
+import * as settings from '../src/lib/settings';
+
+// Mock all dependencies
+jest.mock('../src/lib/settings');
+jest.mock('../src/commands/me');
+jest.mock('../src/commands/projects');
+jest.mock('../src/commands/task-with-details');
+jest.mock('../src/commands/project-statuses');
+jest.mock('../src/commands/about');
+jest.mock('../src/lib/utils', () => ({
+  validateEnvVars: jest.fn()
+}));
+jest.mock('dotenv', () => ({
+  config: jest.fn()
+}));
+
+const mockSettings = settings as jest.Mocked<typeof settings>;
+
+describe('CLI Command Permissions', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    console.log = jest.fn();
+    console.error = jest.fn();
+  });
+
+  describe('Command permission checks', () => {
+    it('should allow execution when command is in allowed list', () => {
+      mockSettings.isCommandAllowed.mockReturnValue(true);
+      mockSettings.getAllowedCommands.mockReturnValue(['me', 'projects']);
+
+      expect(mockSettings.isCommandAllowed('me')).toBe(true);
+      expect(mockSettings.isCommandAllowed('projects')).toBe(true);
+    });
+
+    it('should deny execution when command is not in allowed list', () => {
+      mockSettings.isCommandAllowed.mockImplementation((cmd: string) =>
+        ['me', 'projects'].includes(cmd)
+      );
+      mockSettings.getAllowedCommands.mockReturnValue(['me', 'projects']);
+
+      expect(mockSettings.isCommandAllowed('task-with-details')).toBe(false);
+      expect(mockSettings.isCommandAllowed('project-statuses')).toBe(false);
+    });
+
+    it('should allow all commands when "all" is specified', () => {
+      mockSettings.isCommandAllowed.mockReturnValue(true);
+      mockSettings.getAllowedCommands.mockReturnValue(['all']);
+
+      expect(mockSettings.isCommandAllowed('me')).toBe(true);
+      expect(mockSettings.isCommandAllowed('projects')).toBe(true);
+      expect(mockSettings.isCommandAllowed('task-with-details')).toBe(true);
+      expect(mockSettings.isCommandAllowed('project-statuses')).toBe(true);
+    });
+  });
+
+  describe('Permission wrapper behavior', () => {
+    it('should execute command when permission is granted', async () => {
+      mockSettings.isCommandAllowed.mockReturnValue(true);
+
+      const mockCommand = jest.fn().mockResolvedValue(undefined);
+      const wrappedCommand = async (...args: any[]) => {
+        if (!mockSettings.isCommandAllowed('me')) {
+          console.error('Command not allowed');
+          process.exit(1);
+        }
+        return mockCommand(...args);
+      };
+
+      await wrappedCommand('arg1', 'arg2');
+
+      expect(mockCommand).toHaveBeenCalledWith('arg1', 'arg2');
+      expect(console.error).not.toHaveBeenCalled();
+    });
+
+    it('should block command execution when permission is denied', async () => {
+      mockSettings.isCommandAllowed.mockReturnValue(false);
+      mockSettings.getAllowedCommands.mockReturnValue(['me', 'projects']);
+
+      const mockCommand = jest.fn().mockResolvedValue(undefined);
+      const processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('Process exit');
+      });
+
+      const wrappedCommand = async (...args: any[]) => {
+        if (!mockSettings.isCommandAllowed('task-with-details')) {
+          console.error("Command 'task-with-details' is not allowed.");
+          console.log('Allowed commands: ' + mockSettings.getAllowedCommands().join(', '));
+          process.exit(1);
+        }
+        return mockCommand(...args);
+      };
+
+      await expect(wrappedCommand()).rejects.toThrow('Process exit');
+
+      expect(mockCommand).not.toHaveBeenCalled();
+      expect(console.error).toHaveBeenCalledWith(expect.stringContaining('not allowed'));
+      expect(console.log).toHaveBeenCalledWith(expect.stringContaining('me, projects'));
+      expect(processExitSpy).toHaveBeenCalledWith(1);
+
+      processExitSpy.mockRestore();
+    });
+
+    it('should pass arguments correctly to allowed commands', async () => {
+      mockSettings.isCommandAllowed.mockReturnValue(true);
+
+      const mockCommand = jest.fn().mockResolvedValue(undefined);
+      const wrappedCommand = async (...args: any[]) => {
+        if (!mockSettings.isCommandAllowed('task-with-details')) {
+          process.exit(1);
+        }
+        return mockCommand(...args);
+      };
+
+      await wrappedCommand('BP-123');
+
+      expect(mockCommand).toHaveBeenCalledWith('BP-123');
+      expect(mockCommand).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Integration scenarios', () => {
+    it('should handle scenario: only me and projects allowed', () => {
+      mockSettings.isCommandAllowed.mockImplementation((cmd: string) =>
+        ['me', 'projects'].includes(cmd)
+      );
+      mockSettings.getAllowedCommands.mockReturnValue(['me', 'projects']);
+
+      expect(mockSettings.isCommandAllowed('me')).toBe(true);
+      expect(mockSettings.isCommandAllowed('projects')).toBe(true);
+      expect(mockSettings.isCommandAllowed('task-with-details')).toBe(false);
+      expect(mockSettings.isCommandAllowed('project-statuses')).toBe(false);
+      expect(mockSettings.isCommandAllowed('about')).toBe(false);
+    });
+
+    it('should handle scenario: all commands allowed', () => {
+      mockSettings.isCommandAllowed.mockReturnValue(true);
+      mockSettings.getAllowedCommands.mockReturnValue(['all']);
+
+      const commands = ['me', 'projects', 'task-with-details', 'project-statuses', 'about'];
+      commands.forEach(cmd => {
+        expect(mockSettings.isCommandAllowed(cmd)).toBe(true);
+      });
+    });
+
+    it('should handle scenario: no commands allowed except about', () => {
+      mockSettings.isCommandAllowed.mockImplementation((cmd: string) =>
+        cmd === 'about'
+      );
+      mockSettings.getAllowedCommands.mockReturnValue([]);
+
+      expect(mockSettings.isCommandAllowed('me')).toBe(false);
+      expect(mockSettings.isCommandAllowed('projects')).toBe(false);
+      expect(mockSettings.isCommandAllowed('about')).toBe(true);
+    });
+  });
+});