git:20251210.11d096a to git:20251210.872a39c

17 added, 5 removed. Audit A to A.

# JIRA CLI Project Guide

## Project Overview

Modern, extensible JIRA command-line interface built with Factory pattern and Commander.js. Provides full CRUD operations for issues, projects, and sprints with beautiful terminal UX.

+ ## CLI Design Philosophy

+ - **Non-Interactive**: All commands require explicit CLI arguments for full automation support

+ - **Scriptable**: Designed for CI/CD pipelines and shell scripts

+ - **No Prompts**: All input via flags or environment variables, no interactive prompts

+ - **Description Files**: Use `--description-file` for multi-line content

+ - **Explicit Validation**: Clear error messages with usage examples when options missing

## Architecture

### Design Patterns

- **Factory Pattern**: Command creation via `lib/factory.js`

- **Dependency Injection**: Services injected into commands

- **Commander.js**: CLI framework for command routing and parsing

### Project Structure

```

jira-cli/

├── bin/

│ ├── index.js # CLI entry point

│ ├── root.js # Root command setup

│ └── commands/ # Command implementations

│ ├── config.js # Configuration management

- │ ├── init.js # Interactive setup

│ ├── issue.js # Issue CRUD operations

│ ├── project.js # Project operations

│ └── sprint.js # Sprint management

├── lib/

│ ├── jira-client.js # JIRA API client (axios)

│ ├── config.js # Config management (conf package)

│ ├── factory.js # Command factory

│ ├── iostreams.js # I/O abstractions for testing

│ ├── utils.js # Utility functions

│ └── analytics.js # Usage analytics

└── tests/ # Jest unit tests

```

### Key Dependencies

- **commander**: CLI framework

- **axios**: HTTP client for JIRA API

- - **inquirer**: Interactive prompts

- **chalk**: Terminal colors

- **ora**: Spinners and progress indicators

- **cli-table3**: Formatted table output

- **conf**: Cross-platform config storage

## Development Guidelines

### Code Style

- JavaScript (CommonJS), not TypeScript

- Self-documenting code preferred over comments (per global CLAUDE.md)

- Use descriptive variable/function names

- Follow existing patterns in the codebase

### Adding New Commands

1. Create command file in `bin/commands/`

2. Implement command logic following existing patterns

3. Register command in `bin/root.js`

4. Add tests in `tests/commands/`

5. Update README.md with command documentation

### API Client Usage

- Use `lib/jira-client.js` for all JIRA API calls

- Handle authentication via config (API token + username)

- Implement proper error handling with user-friendly messages

- Use iostreams for output (supports testing and mocking)

### Configuration

- Config stored via `conf` package (platform-specific locations)

- - Support both environment variables and interactive setup

+ - Support environment variables and CLI flags (no interactive setup)

- Environment variables: `JIRA_HOST`, `JIRA_API_TOKEN`, `JIRA_USERNAME`

- Legacy support: `JIRA_DOMAIN`, `JIRA_USERNAME`, `JIRA_API_TOKEN`

+ - CLI flags: `jira config --server <url> --username <email> --token <token>`

+ ### Issue Management Patterns

+ - **Create**: Require `--project`, `--type`, `--summary` flags

+ - **Update**: Require at least one field flag

+ - **Delete**: Require `--force` flag (no confirmation prompt)

+ - **Description Files**: Support `--description-file <path>` for multi-line content

## Testing

### Running Tests

```bash

npm test # Run all tests

npm run test:watch # Watch mode

npm run test:coverage # Coverage report

```

### Test Strategy

- Unit tests for all commands and lib functions

- Mock JIRA API calls using Jest mocks

- Use iostreams abstraction for CLI I/O testing

- Maintain high test coverage

### Writing Tests

- Place tests in `tests/` directory mirroring source structure

- Use descriptive test names

- - Mock external dependencies (axios, inquirer)

+ - Mock external dependencies (axios)

- Test both success and error cases

## Release Process

### Conventional Commits (Required)

All commits must follow [Conventional Commits](https://www.conventionalcommits.org/) format:

- `feat:` - New features (minor version bump)

- `fix:` - Bug fixes (patch version bump)

- `docs:` - Documentation only

- `refactor:` - Code refactoring

- `test:` - Test additions/changes

- `chore:` - Build/tooling changes

### Automated Release

- Merge to `main` triggers semantic-release

- Version bumped automatically based on commit types

- Changelog generated from commit messages

- NPM publish automated via GitHub Actions

### Manual Release Fallback

See AGENTS.md for emergency release procedures if automation fails.

## Common Tasks

### Adding JIRA API Integration

1. Add method to `lib/jira-client.js`

2. Use axios for HTTP requests

3. Handle authentication headers automatically

4. Return meaningful error messages

5. Add unit tests with mocked responses

### Improving UX

- Use `chalk` for colored output

- Use `ora` for loading indicators

- Use `cli-table3` for tabular data

- - Use `inquirer` for interactive prompts

- Provide clear error messages with actionable guidance

+ - Show usage examples in error messages when required options missing

### Debugging

```bash

DEBUG=jira-cli* jira issue --list

JIRA_CLI_ANALYTICS=false jira config --show

```

## Important Notes

- JIRA API uses Bearer token authentication (API tokens, not passwords)

- Support both JIRA Cloud and JIRA Data Center APIs

- Handle rate limiting and network errors gracefully

- Respect user privacy (analytics opt-out via `JIRA_CLI_ANALYTICS=false`)

- Always test with real JIRA instance before releasing