jira-as 1.0.0__tar.gz

jira_as-1.0.0/.gitignore

@@ -0,0 +1,76 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

jira_as-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jason Krueger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jira_as-1.0.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: jira-as
+Version: 1.0.0
+Summary: JIRA Assistant Skills library and CLI - HTTP client, configuration, error handling, and jira-as command for JIRA REST API automation
+Project-URL: Homepage, https://github.com/grandcamel/jira-as-lib
+Project-URL: Repository, https://github.com/grandcamel/jira-as-lib
+Project-URL: Issues, https://github.com/grandcamel/jira-as-lib/issues
+Project-URL: Changelog, https://github.com/grandcamel/jira-as-lib/blob/main/CHANGELOG.md
+Author-email: Jason Krueger <grandcamel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,assistant,atlassian,automation,claude,jira,rest,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Groupware
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: assistant-skills-lib>=1.0.0
+Requires-Dist: click>=8.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: nest-asyncio>=1.5.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: responses>=0.24.0; extra == 'dev'
+Requires-Dist: types-requests>=2.28.0; extra == 'dev'
+Requires-Dist: types-tabulate>=0.9.0; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=24.0.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# JIRA AS
+
+[![PyPI version](https://badge.fury.io/py/jira-as.svg)](https://badge.fury.io/py/jira-as)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python library and CLI for JIRA REST API automation, providing HTTP client, configuration management, error handling, and utilities for the [JIRA Assistant Skills](https://github.com/grandcamel/Jira-Assistant-Skills) Claude Code plugin.
+
+## Installation
+
+```bash
+pip install jira-as
+```
+
+With optional keyring support for secure credential storage:
+
+```bash
+pip install jira-as[keyring]
+```
+
+## Features
+
+- **CLI (`jira-as`)**: Command-line interface for JIRA operations
+- **JiraClient**: HTTP client with automatic retry logic and exponential backoff
+- **ConfigManager**: Multi-source configuration (env vars > keychain > settings.local.json > settings.json > defaults)
+- **Error Handling**: Exception hierarchy mapping HTTP status codes to domain exceptions
+- **Validators**: Input validation for issue keys, project keys, JQL queries, URLs, and more
+- **Formatters**: Output formatting for tables, JSON, CSV export
+- **ADF Helper**: Atlassian Document Format conversion (markdown/text to ADF and back)
+- **Time Utils**: JIRA time format parsing and formatting (e.g., '2h', '1d 4h 30m')
+- **Cache**: SQLite-based caching with TTL support for API responses
+- **Credential Manager**: Secure credential storage via system keychain or JSON fallback
+- **Mock Client**: Full mock implementation for testing without JIRA access
+
+## Quick Start
+
+### Configuration
+
+Set environment variables:
+
+```bash
+export JIRA_API_TOKEN="your-api-token"  # Get from https://id.atlassian.com/manage-profile/security/api-tokens
+export JIRA_EMAIL="your-email@company.com"
+export JIRA_SITE_URL="https://your-company.atlassian.net"
+```
+
+### CLI Usage
+
+```bash
+# Get an issue
+jira-as issue get PROJ-123
+
+# Search issues
+jira-as search query "project = PROJ AND status = Open"
+
+# Create an issue
+jira-as issue create PROJ --summary "New task" --type Task
+
+# Transition an issue
+jira-as lifecycle transition PROJ-123 "In Progress"
+
+# See all commands
+jira-as --help
+```
+
+### Library Usage
+
+```python
+from jira_as import get_jira_client, handle_errors
+
+@handle_errors
+def main():
+    # Get a configured JIRA client (use as context manager)
+    with get_jira_client() as client:
+        # Fetch an issue
+        issue = client.get_issue('PROJ-123')
+        print(f"Summary: {issue['fields']['summary']}")
+
+        # Search issues with JQL
+        results = client.search_issues('project = PROJ AND status = Open')
+        for issue in results['issues']:
+            print(f"{issue['key']}: {issue['fields']['summary']}")
+
+if __name__ == '__main__':
+    main()
+```
+
+## Core Components
+
+### JiraClient
+
+```python
+from jira_as import JiraClient
+
+# Direct instantiation (prefer get_jira_client() for config management)
+client = JiraClient(
+    base_url="https://your-company.atlassian.net",
+    email="your-email@company.com",
+    api_token="your-api-token"
+)
+
+# Use as context manager
+with client:
+    issue = client.get_issue('PROJ-123')
+    client.create_issue(project_key='PROJ', summary='New issue', issue_type='Task')
+    client.transition_issue('PROJ-123', 'Done')
+```
+
+### Error Handling
+
+```python
+from jira_as import (
+    JiraError,
+    AuthenticationError,
+    PermissionError,
+    NotFoundError,
+    handle_errors
+)
+
+@handle_errors
+def main():
+    # Exceptions are caught and formatted nicely
+    pass
+
+# Or handle manually
+try:
+    with get_jira_client() as client:
+        client.get_issue('INVALID-999')
+except NotFoundError as e:
+    print(f"Issue not found: {e}")
+except AuthenticationError as e:
+    print(f"Auth failed: {e}")
+except JiraError as e:
+    print(f"JIRA error: {e}")
+```
+
+### Validators
+
+```python
+from jira_as import (
+    validate_issue_key,
+    validate_project_key,
+    validate_jql,
+    validate_url,
+    ValidationError
+)
+
+try:
+    key = validate_issue_key('PROJ-123')  # Returns 'PROJ-123'
+    key = validate_issue_key('invalid')   # Raises ValidationError
+except ValidationError as e:
+    print(f"Invalid input: {e}")
+```
+
+### ADF Helper
+
+```python
+from jira_as import (
+    markdown_to_adf,
+    text_to_adf,
+    adf_to_text
+)
+
+# Convert markdown to ADF for JIRA
+adf = markdown_to_adf("**Bold** and *italic* text")
+
+# Convert plain text to ADF
+adf = text_to_adf("Simple text content")
+
+# Extract text from ADF
+text = adf_to_text(adf_document)
+```
+
+### Time Utils
+
+```python
+from jira_as import (
+    parse_time_string,
+    format_seconds,
+    parse_relative_date
+)
+
+# Parse JIRA time format to seconds
+seconds = parse_time_string('2h 30m')  # 9000
+
+# Format seconds to JIRA time format
+time_str = format_seconds(9000)  # '2h 30m'
+
+# Parse relative dates
+dt = parse_relative_date('yesterday')
+dt = parse_relative_date('2025-01-15')
+```
+
+## Mock Mode
+
+For testing without JIRA access:
+
+```bash
+export JIRA_MOCK_MODE=true
+jira-as issue get DEMO-85  # Returns mock data
+```
+
+```python
+import os
+os.environ['JIRA_MOCK_MODE'] = 'true'
+
+from jira_as import get_jira_client
+
+with get_jira_client() as client:  # Returns MockJiraClient
+    issue = client.get_issue('DEMO-85')  # Mock data
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/grandcamel/jira-as-lib.git
+cd jira-as-lib
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black src tests
+isort src tests
+
+# Type checking
+mypy src
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

jira_as-1.0.0/README.md

@@ -0,0 +1,236 @@
+# JIRA AS
+
+[![PyPI version](https://badge.fury.io/py/jira-as.svg)](https://badge.fury.io/py/jira-as)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python library and CLI for JIRA REST API automation, providing HTTP client, configuration management, error handling, and utilities for the [JIRA Assistant Skills](https://github.com/grandcamel/Jira-Assistant-Skills) Claude Code plugin.
+
+## Installation
+
+```bash
+pip install jira-as
+```
+
+With optional keyring support for secure credential storage:
+
+```bash
+pip install jira-as[keyring]
+```
+
+## Features
+
+- **CLI (`jira-as`)**: Command-line interface for JIRA operations
+- **JiraClient**: HTTP client with automatic retry logic and exponential backoff
+- **ConfigManager**: Multi-source configuration (env vars > keychain > settings.local.json > settings.json > defaults)
+- **Error Handling**: Exception hierarchy mapping HTTP status codes to domain exceptions
+- **Validators**: Input validation for issue keys, project keys, JQL queries, URLs, and more
+- **Formatters**: Output formatting for tables, JSON, CSV export
+- **ADF Helper**: Atlassian Document Format conversion (markdown/text to ADF and back)
+- **Time Utils**: JIRA time format parsing and formatting (e.g., '2h', '1d 4h 30m')
+- **Cache**: SQLite-based caching with TTL support for API responses
+- **Credential Manager**: Secure credential storage via system keychain or JSON fallback
+- **Mock Client**: Full mock implementation for testing without JIRA access
+
+## Quick Start
+
+### Configuration
+
+Set environment variables:
+
+```bash
+export JIRA_API_TOKEN="your-api-token"  # Get from https://id.atlassian.com/manage-profile/security/api-tokens
+export JIRA_EMAIL="your-email@company.com"
+export JIRA_SITE_URL="https://your-company.atlassian.net"
+```
+
+### CLI Usage
+
+```bash
+# Get an issue
+jira-as issue get PROJ-123
+
+# Search issues
+jira-as search query "project = PROJ AND status = Open"
+
+# Create an issue
+jira-as issue create PROJ --summary "New task" --type Task
+
+# Transition an issue
+jira-as lifecycle transition PROJ-123 "In Progress"
+
+# See all commands
+jira-as --help
+```
+
+### Library Usage
+
+```python
+from jira_as import get_jira_client, handle_errors
+
+@handle_errors
+def main():
+    # Get a configured JIRA client (use as context manager)
+    with get_jira_client() as client:
+        # Fetch an issue
+        issue = client.get_issue('PROJ-123')
+        print(f"Summary: {issue['fields']['summary']}")
+
+        # Search issues with JQL
+        results = client.search_issues('project = PROJ AND status = Open')
+        for issue in results['issues']:
+            print(f"{issue['key']}: {issue['fields']['summary']}")
+
+if __name__ == '__main__':
+    main()
+```
+
+## Core Components
+
+### JiraClient
+
+```python
+from jira_as import JiraClient
+
+# Direct instantiation (prefer get_jira_client() for config management)
+client = JiraClient(
+    base_url="https://your-company.atlassian.net",
+    email="your-email@company.com",
+    api_token="your-api-token"
+)
+
+# Use as context manager
+with client:
+    issue = client.get_issue('PROJ-123')
+    client.create_issue(project_key='PROJ', summary='New issue', issue_type='Task')
+    client.transition_issue('PROJ-123', 'Done')
+```
+
+### Error Handling
+
+```python
+from jira_as import (
+    JiraError,
+    AuthenticationError,
+    PermissionError,
+    NotFoundError,
+    handle_errors
+)
+
+@handle_errors
+def main():
+    # Exceptions are caught and formatted nicely
+    pass
+
+# Or handle manually
+try:
+    with get_jira_client() as client:
+        client.get_issue('INVALID-999')
+except NotFoundError as e:
+    print(f"Issue not found: {e}")
+except AuthenticationError as e:
+    print(f"Auth failed: {e}")
+except JiraError as e:
+    print(f"JIRA error: {e}")
+```
+
+### Validators
+
+```python
+from jira_as import (
+    validate_issue_key,
+    validate_project_key,
+    validate_jql,
+    validate_url,
+    ValidationError
+)
+
+try:
+    key = validate_issue_key('PROJ-123')  # Returns 'PROJ-123'
+    key = validate_issue_key('invalid')   # Raises ValidationError
+except ValidationError as e:
+    print(f"Invalid input: {e}")
+```
+
+### ADF Helper
+
+```python
+from jira_as import (
+    markdown_to_adf,
+    text_to_adf,
+    adf_to_text
+)
+
+# Convert markdown to ADF for JIRA
+adf = markdown_to_adf("**Bold** and *italic* text")
+
+# Convert plain text to ADF
+adf = text_to_adf("Simple text content")
+
+# Extract text from ADF
+text = adf_to_text(adf_document)
+```
+
+### Time Utils
+
+```python
+from jira_as import (
+    parse_time_string,
+    format_seconds,
+    parse_relative_date
+)
+
+# Parse JIRA time format to seconds
+seconds = parse_time_string('2h 30m')  # 9000
+
+# Format seconds to JIRA time format
+time_str = format_seconds(9000)  # '2h 30m'
+
+# Parse relative dates
+dt = parse_relative_date('yesterday')
+dt = parse_relative_date('2025-01-15')
+```
+
+## Mock Mode
+
+For testing without JIRA access:
+
+```bash
+export JIRA_MOCK_MODE=true
+jira-as issue get DEMO-85  # Returns mock data
+```
+
+```python
+import os
+os.environ['JIRA_MOCK_MODE'] = 'true'
+
+from jira_as import get_jira_client
+
+with get_jira_client() as client:  # Returns MockJiraClient
+    issue = client.get_issue('DEMO-85')  # Mock data
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/grandcamel/jira-as-lib.git
+cd jira-as-lib
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black src tests
+isort src tests
+
+# Type checking
+mypy src
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.