Skip to content

CLAUDE.md

Latest commit

 

History

History
152 lines (126 loc) · 5.44 KB

CLAUDE.md

File metadata and controls

152 lines (126 loc) · 5.44 KB
Raw

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
│       ├── 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
  • 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 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

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)
  • Test both success and error cases

Release Process

Conventional Commits (Required)

All commits must follow Conventional Commits 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
  • Provide clear error messages with actionable guidance
  • Show usage examples in error messages when required options missing

Debugging

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