# jps-jira-utils

![Build & Test](https://github.com/jai-python3/jps-jira-utils/actions/workflows/test.yml/badge.svg)
![Publish to PyPI](https://github.com/jai-python3/jps-jira-utils/actions/workflows/publish-to-pypi.yml/badge.svg)
[![codecov](https://codecov.io/gh/jai-python3/jps-jira-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/jai-python3/jps-jira-utils)
[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](#)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](#)

> **A clean, modular, production-grade toolkit for Jira power users**  
> Built with Typer, rich logging, and full test coverage.

## Features

- `add_comment.py` — Add rich comments (with optional file attachments) to any Jira issue
  - Interactive multiline input (ends on two blank lines)
  - Load comment from file (`--comment-file`)
  - Attach files with pre-canned or custom notes (STDOUT, STDERR, log file, README, etc.)
  - Final confirmation table before posting
  - Full logging with structured output
- Secure credential loading via `~/.jira.env` (never in code or CLI)
- Clean, maintainable, fully tested codebase using modern Python best practices
- Zero external runtime dependencies beyond `requests`, `typer`, and `python-dotenv`

## Installation

### From source (recommended for development)

```bash
git clone https://github.com/jai-python3/jps-jira-utils.git
cd jps-jira-utils
make install    # creates .venv and installs in editable mode
```


From PyPI (coming soon)

```bash
pip install jps-jira-utils
```

Prerequisites

Create a ~/.jira.env file with your Jira Cloud credentials:

```env
JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=your.email@company.com
JIRA_API_TOKEN=your_api_token_here
```

Generate your API token at: https://id.atlassian.com/manage-profile/security/api-tokens


## Usage

Add a comment interactively

```bash
jps-add-comment JPS-1234
```

Add a comment from a file + attach a log



```bash
jps-add-comment JPS-1234 \
  --comment-file results.txt \
  --attach-file test-run.log
```


Full help

```bash
jps-add-comment --help
```


## Development
```bash
# Format, lint, and fix everything
make fix
make format
make lint
```

### Run tests with coverage

```bash
make test
```

### Run pre-commit hooks (recommended)

```bash
pre-commit run --all-files
```


## Project Structure
```text
src/jps_jira_utils/
├── add_comment.py        # Typer CLI entrypoint
├── jira_helper.py        # Credential loading
├── logging_helper.py     # Structured logging setup
└── prompt_helper.py      # Interactive input utilities

tests/                    # Includes coverage, darglint-compliant
```


##  Contributing

Contributions are welcome! Please:

Use pre-commit hooks
Write tests for new features
Follow Google-style docstrings
Keep the codebase clean and modular

## License

MIT License © Jaideep Sundaram