jira2ai-core 0.1.0__tar.gz

jira2ai_core-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.3
+Name: jira2ai-core
+Version: 0.1.0
+Summary: Shared core package for Jira AI integrations
+Author: en-ver
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jira2py==0.5.0
+Requires-Dist: marklassian>=0.1.0
+Requires-Dist: pathvalidate>=3.3.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyadf>=0.3.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# jira2ai-core
+
+Shared Jira operations and formatting utilities used by the `jira2mcp` MCP adapter and the `jira2cli` CLI adapter.
+
+This package is part of the workspace in this repository. It is not the end-user MCP entry point; for MCP installs, keep using `uvx jira2mcp`.
+
+## Local development
+
+From the workspace root:
+
+```bash
+uv sync --all-packages --group dev
+uv build --package jira2ai-core
+```
+
+## Maintainers
+
+`jira2ai-core` has its own version and future tags use `jira2ai-core-vX.Y.Z`.
+
+Release sequencing, stop gates, and Trusted Publishing boundaries:
+
+- <https://github.com/en-ver/jira2ai/blob/main/docs/releasing.md>
+- <https://github.com/en-ver/jira2ai/blob/main/CONTRIBUTING.md>

jira2ai_core-0.1.0/README.md

@@ -0,0 +1,23 @@
+# jira2ai-core
+
+Shared Jira operations and formatting utilities used by the `jira2mcp` MCP adapter and the `jira2cli` CLI adapter.
+
+This package is part of the workspace in this repository. It is not the end-user MCP entry point; for MCP installs, keep using `uvx jira2mcp`.
+
+## Local development
+
+From the workspace root:
+
+```bash
+uv sync --all-packages --group dev
+uv build --package jira2ai-core
+```
+
+## Maintainers
+
+`jira2ai-core` has its own version and future tags use `jira2ai-core-vX.Y.Z`.
+
+Release sequencing, stop gates, and Trusted Publishing boundaries:
+
+- <https://github.com/en-ver/jira2ai/blob/main/docs/releasing.md>
+- <https://github.com/en-ver/jira2ai/blob/main/CONTRIBUTING.md>

jira2ai_core-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "jira2ai-core"
+version = "0.1.0"
+description = "Shared core package for Jira AI integrations"
+readme = "README.md"
+authors = [
+    { name = "en-ver" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.1",
+    "jira2py==0.5.0",
+    "marklassian>=0.1.0",
+    "pathvalidate>=3.3.1",
+    "pydantic>=2.12.5",
+    "pyadf>=0.3.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"

jira2ai_core-0.1.0/src/jira2ai_core/__init__.py

@@ -0,0 +1,26 @@
+"""Shared core package for Jira AI integrations."""
+
+from .errors import (
+    AttachmentDownloadError,
+    AttachmentError,
+    AttachmentPathError,
+    Jira2AIConfigError,
+    Jira2AIError,
+    Jira2AIValidationError,
+    JiraOperationError,
+)
+from .results import OperationResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "AttachmentDownloadError",
+    "AttachmentError",
+    "AttachmentPathError",
+    "Jira2AIConfigError",
+    "Jira2AIError",
+    "Jira2AIValidationError",
+    "JiraOperationError",
+    "OperationResult",
+]

jira2ai_core-0.1.0/src/jira2ai_core/adf.py

@@ -0,0 +1,167 @@
+"""ADF (Atlassian Document Format) conversion utilities.
+
+Uses pyadf for ADF→Markdown (reading from Jira)
+and marklassian for Markdown→ADF (writing to Jira).
+"""
+
+import logging
+from typing import Any
+
+from marklassian import AdfDocument, AdfNode
+from marklassian import markdown_to_adf as _markdown_to_adf
+from pyadf import Document
+
+logger = logging.getLogger(__name__)
+
+
+def adf_to_markdown(adf: Any) -> str:
+    """Convert ADF JSON to Markdown.
+
+    Args:
+        adf: ADF document as a dictionary, or None.
+
+    Returns:
+        Markdown string, or "(none)" if input is empty/invalid.
+    """
+    if not adf or not isinstance(adf, dict):
+        return "(none)"
+
+    try:
+        doc = Document(adf)
+        md = doc.to_markdown()
+        return md.strip() if md else "(none)"
+    except Exception:
+        logger.exception("ADF to Markdown conversion failed, using plain text fallback")
+        return _extract_text_fallback(adf)
+
+
+def markdown_to_adf(markdown: str) -> AdfDocument:
+    """Convert Markdown to ADF JSON.
+
+    Args:
+        markdown: Markdown string.
+
+    Returns:
+        ADF document as a TypedDict.
+    """
+    if not markdown or not markdown.strip():
+        return AdfDocument(type="doc", version=1, content=[])
+
+    try:
+        return _markdown_to_adf(markdown)
+    except Exception:
+        logger.exception("Markdown to ADF conversion failed, wrapping as plain text")
+        return AdfDocument(
+            type="doc",
+            version=1,
+            content=[
+                AdfNode(
+                    type="paragraph",
+                    content=[AdfNode(type="text", text=markdown)],
+                )
+            ],
+        )
+
+
+# --- ADF field detection ---
+
+# System fields known to use ADF format
+_ADF_SYSTEM_FIELDS: set[str] = {"description", "environment"}
+
+# Custom field schema suffix indicating ADF (rich-text paragraph)
+_ADF_CUSTOM_SUFFIX = ":textarea"
+
+
+def is_adf_value(value: Any) -> bool:
+    """Check if a value looks like an ADF document.
+
+    ADF documents are dicts with ``{"type": "doc", "version": 1, "content": [...]}``.
+    """
+    return isinstance(value, dict) and value.get("type") == "doc"
+
+
+def is_adf_field(field_id: str, custom_schema: str = "") -> bool:
+    """Check if a field is known to use ADF format.
+
+    Detection is based on:
+    - Known system fields (description, environment)
+    - Custom field schema containing ':textarea'
+    """
+    if field_id in _ADF_SYSTEM_FIELDS:
+        return True
+    if custom_schema and _ADF_CUSTOM_SUFFIX in custom_schema:
+        return True
+    return False
+
+
+def convert_adf_values(data: dict[str, Any]) -> dict[str, Any]:
+    """Convert any ADF values in a dict to markdown strings.
+
+    Iterates over all values and converts those that look like ADF documents.
+    Non-ADF values are left unchanged.
+    """
+    result = {}
+    for key, value in data.items():
+        if is_adf_value(value):
+            result[key] = adf_to_markdown(value)
+        else:
+            result[key] = value
+    return result
+
+
+def detect_adf_field_ids(fields_metadata: list[dict[str, Any]]) -> set[str]:
+    """Build a set of field IDs that use ADF format.
+
+    Examines field metadata from the Jira fields API and identifies
+    fields that use ADF based on known system fields and custom textarea schema.
+
+    Args:
+        fields_metadata: List of field dicts from ``api.fields.get_fields()``.
+
+    Returns:
+        Set of field IDs that expect ADF format.
+    """
+    adf_ids = set(_ADF_SYSTEM_FIELDS)
+    for field in fields_metadata:
+        field_id = field.get("id", "")
+        schema = field.get("schema", {}) or {}
+        custom = schema.get("custom", "")
+        if custom and _ADF_CUSTOM_SUFFIX in custom:
+            adf_ids.add(field_id)
+    return adf_ids
+
+
+def convert_markdown_fields(
+    fields: dict[str, Any],
+    adf_field_ids: set[str],
+) -> dict[str, Any]:
+    """Convert markdown string values to ADF for known ADF fields.
+
+    Only converts values that are plain strings and whose field ID
+    is in the provided set of ADF field IDs.
+    """
+    result = {}
+    for key, value in fields.items():
+        if key in adf_field_ids and isinstance(value, str):
+            result[key] = markdown_to_adf(value)
+        else:
+            result[key] = value
+    return result
+
+
+def _extract_text_fallback(adf: dict[str, Any]) -> str:
+    """Extract plain text from ADF as a last resort."""
+    texts: list[str] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            if node.get("type") == "text" and "text" in node:
+                texts.append(node["text"])
+            for child in node.get("content", []):
+                walk(child)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(adf)
+    return " ".join(texts).strip() or "(none)"

jira2ai_core-0.1.0/src/jira2ai_core/client.py

@@ -0,0 +1,18 @@
+"""Client helpers for Jira AI integrations."""
+
+from jira2py import JiraAPI
+
+
+def get_api() -> JiraAPI:
+    """Create a JiraAPI instance.
+
+    Credentials are resolved by jira2py from environment variables:
+    JIRA_URL, JIRA_USER, and JIRA_API_TOKEN.
+
+    Returns:
+        Configured JiraAPI instance.
+
+    Raises:
+        ValueError: If any required credential is missing.
+    """
+    return JiraAPI()

jira2ai_core-0.1.0/src/jira2ai_core/errors.py

@@ -0,0 +1,55 @@
+"""Adapter-neutral error contracts for shared Jira operations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+class Jira2AIError(Exception):
+    """Base error for shared Jira AI core logic."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = dict(details or {})
+
+
+class Jira2AIValidationError(Jira2AIError):
+    """Raised when tool or operation input is invalid."""
+
+
+class Jira2AIConfigError(Jira2AIError):
+    """Raised when required Jira/client configuration is missing or invalid."""
+
+
+class JiraOperationError(Jira2AIError):
+    """Raised when a Jira API operation fails."""
+
+
+class AttachmentError(Jira2AIError):
+    """Base error for attachment-related failures."""
+
+
+class AttachmentPathError(AttachmentError):
+    """Raised when an attachment path is unsafe or outside allowed boundaries."""
+
+
+class AttachmentDownloadError(AttachmentError):
+    """Raised when an attachment download fails."""
+
+
+__all__ = [
+    "AttachmentDownloadError",
+    "AttachmentError",
+    "AttachmentPathError",
+    "Jira2AIConfigError",
+    "Jira2AIError",
+    "Jira2AIValidationError",
+    "JiraOperationError",
+]

jira2ai_core-0.1.0/src/jira2ai_core/formatters.py

@@ -0,0 +1,323 @@
+"""Output formatting functions for Jira data."""
+
+import json
+from typing import Any
+
+from .adf import adf_to_markdown, is_adf_value
+from .models import (
+    FieldMeta,
+    IssueType,
+    JiraComment,
+    JiraIssue,
+    SearchResult,
+    user_display,
+)
+from .utils import format_date, format_size
+
+DEFAULT_FIELDS = [
+    "summary",
+    "status",
+    "issuetype",
+    "priority",
+    "assignee",
+    "reporter",
+    "created",
+    "updated",
+    "labels",
+    "components",
+    "fixVersions",
+    "description",
+    "comment",
+    "attachment",
+    "subtasks",
+    "issuelinks",
+]
+
+# Fields that format_issue_full knows how to render as markdown.
+_FORMATTED_FIELDS = set(DEFAULT_FIELDS)
+
+
+def _section(title: str) -> str:
+    """Return a decorated section heading: ``--- [TITLE] ---``."""
+    return f"--- [{title.upper()}] ---"
+
+
+def _field_label(field_id: str, names_map: dict[str, str]) -> str:
+    """Return a display label for a field: 'Display Name (field_id)' or just field_id."""
+    display = names_map.get(field_id)
+    if display and display != field_id:
+        return f"{display} ({field_id})"
+    return field_id
+
+
+def format_issue_full(
+    issue: JiraIssue,
+    *,
+    url: str = "",
+    requested_fields: list[str] | None = None,
+    field_names: dict[str, str] | None = None,
+) -> str:
+    """Format a full issue for display.
+
+    Standard fields are rendered as readable markdown. Any extra fields
+    (requested but not in the standard set) are appended with display names.
+    ADF rich-text fields are auto-converted to markdown; others shown as JSON.
+    Comments are shown as a count only — use jira_comments for details.
+    """
+    f = issue.fields
+
+    lines: list[str] = [
+        f"Key: {issue.key}",
+        f"Summary: {f.summary}",
+        f"Status: {_named(f.status)}",
+        f"Type: {_named(f.issuetype)}",
+        f"Priority: {_named(f.priority)}",
+        f"Assignee: {user_display(f.assignee)}",
+        f"Reporter: {user_display(f.reporter)}",
+        f"Created: {format_date(f.created)}",
+        f"Updated: {format_date(f.updated)}",
+    ]
+
+    if f.labels:
+        lines.append(f"Labels: {', '.join(f.labels)}")
+
+    if f.components:
+        lines.append(f"Components: {', '.join(c.name for c in f.components)}")
+
+    if f.fixVersions:
+        lines.append(f"Fix Versions: {', '.join(v.name for v in f.fixVersions)}")
+
+    if url:
+        lines.append(f"URL: {url}")
+
+    # Comments — count in header, direct to jira_comments tool for details
+    cp = f.comment
+    total = cp.total if cp else 0
+    if total > 0:
+        lines.append(f"Comments: {total} (use jira_comments tool to read them)")
+    else:
+        lines.append("Comments: none")
+
+    # Attachments
+    if f.attachment:
+        lines.append("")
+        lines.append(_section(f"Attachments ({len(f.attachment)})"))
+        lines.append("Use jira_attachment tool with the attachment id to download")
+        for att in f.attachment:
+            lines.append(
+                f"- {att.filename or '?'} (id: {att.id}, {att.mimeType}, {format_size(att.size)})"
+            )
+
+    # Subtasks
+    if f.subtasks:
+        lines.append("")
+        lines.append(_section(f"Subtasks ({len(f.subtasks)})"))
+        for st in f.subtasks:
+            status = _named(st.fields.status)
+            lines.append(f"- {st.key}: {st.fields.summary} [{status}]")
+
+    # Issue Links
+    if f.issuelinks:
+        lines.append("")
+        lines.append(_section(f"Issue Links ({len(f.issuelinks)})"))
+        for link in f.issuelinks:
+            if link.outwardIssue:
+                target = link.outwardIssue
+                direction = link.type.outward
+            elif link.inwardIssue:
+                target = link.inwardIssue
+                direction = link.type.inward
+            else:
+                continue
+            status = _named(target.fields.status)
+            lines.append(
+                f"- {direction} {target.key}: {target.fields.summary} [{status}] (link id: {link.id})"
+            )
+
+    # Description
+    lines.append("")
+    lines.append(_section("Description"))
+    lines.append(adf_to_markdown(f.description))
+
+    # Extra fields — anything requested but not in the standard formatted set
+    if requested_fields:
+        extra_names = [f for f in requested_fields if f not in _FORMATTED_FIELDS]
+        if extra_names:
+            extra_data: dict[str, Any] = {}
+            raw_fields = issue.fields.model_extra or {}
+            # Also check declared attributes in case of overlap
+            for name in extra_names:
+                if name in raw_fields:
+                    extra_data[name] = raw_fields[name]
+                elif hasattr(issue.fields, name):
+                    val = getattr(issue.fields, name)
+                    if val is not None:
+                        extra_data[name] = val
+            if extra_data:
+                names_map = field_names or {}
+                lines.append("")
+                lines.append(_section("Additional Fields"))
+                # Separate ADF fields (render as markdown) from plain fields (JSON)
+                adf_extra: dict[str, Any] = {}
+                plain_fields: dict[str, Any] = {}
+                for k, v in extra_data.items():
+                    if is_adf_value(v):
+                        adf_extra[k] = v
+                    else:
+                        plain_fields[k] = v
+                for k, v in adf_extra.items():
+                    label = _field_label(k, names_map)
+                    lines.append(_section(label))
+                    lines.append(adf_to_markdown(v))
+                    lines.append("")
+                if plain_fields:
+                    # Remap keys to include display names
+                    labeled = {
+                        _field_label(k, names_map): v for k, v in plain_fields.items()
+                    }
+                    lines.append("```json")
+                    lines.append(json.dumps(labeled, indent=2, default=str))
+                    lines.append("```")
+
+    return "\n".join(lines)
+
+
+def format_comment(comment: JiraComment) -> str:
+    """Format a single comment.
+
+    Args:
+        comment: Parsed Jira comment.
+
+    Returns:
+        Formatted comment string.
+    """
+    author = user_display(comment.author)
+    created = format_date(comment.created)
+    updated = format_date(comment.updated)
+    body = adf_to_markdown(comment.body)
+
+    date_str = created
+    if updated != created:
+        date_str += f" (edited {updated})"
+
+    return f"### {author} — {date_str}\n{body}"
+
+
+def format_search_results(result: SearchResult, jql: str = "") -> str:
+    """Format search results as a compact list.
+
+    Args:
+        result: Parsed search response.
+        jql: The JQL query that produced these results.
+
+    Returns:
+        Formatted results string.
+    """
+    if not result.issues:
+        return f"No issues found for JQL: {jql}" if jql else "No issues found."
+
+    lines: list[str] = []
+    for issue in result.issues:
+        f = issue.fields
+        status = _named(f.status)
+        lines.append(
+            f"{issue.key} — {f.summary} [{status}] ({user_display(f.assignee)})"
+        )
+
+    output = f"Found {len(result.issues)} issue(s)\n\n" + "\n".join(lines)
+
+    if result.nextPageToken:
+        output += "\n\n(more results available — refine JQL or increase max_results)"
+
+    return output
+
+
+def format_issue_type_list(project_key: str, issue_types: list[IssueType]) -> str:
+    """Format a list of issue types for display.
+
+    Args:
+        project_key: Project key.
+        issue_types: Parsed issue type list.
+
+    Returns:
+        Formatted string.
+    """
+    if not issue_types:
+        return f"No issue types found for project {project_key}"
+    lines = [f"Issue types for {project_key}:\n"]
+    for it in issue_types:
+        subtask = " (subtask)" if it.subtask else ""
+        lines.append(f"  • {it.name} (id: {it.id}){subtask}")
+    return "\n".join(lines)
+
+
+def format_field_metadata(
+    project_key: str, type_name: str, fields: list[FieldMeta]
+) -> str:
+    """Format field metadata for display.
+
+    Args:
+        project_key: Project key or issue key.
+        type_name: Issue type name or "edit".
+        fields: Parsed field metadata list.
+
+    Returns:
+        Formatted string with required and optional fields.
+    """
+    if not fields:
+        return f"No fields found for {project_key} / {type_name}"
+
+    required = [f for f in fields if f.required]
+    optional = [f for f in fields if not f.required]
+
+    lines = [f"Fields for {project_key} / {type_name}:\n"]
+
+    if required:
+        lines.append("Required:")
+        for f in required:
+            lines.extend(_format_field(f))
+
+    if optional:
+        lines.append("")
+        lines.append("Optional:")
+        for f in optional:
+            lines.extend(_format_field(f))
+
+    return "\n".join(lines)
+
+
+def _named(resource: Any) -> str:
+    """Extract name from an optional NamedResource."""
+    return resource.name if resource else "—"
+
+
+def _format_field(f: FieldMeta) -> list[str]:
+    """Format a single field's metadata."""
+    lines: list[str] = []
+    schema_type = f.schema.type if f.schema else "unknown"
+    custom = f.schema.custom if f.schema else ""
+    custom_suffix = f" ({custom.split(':')[-1]})" if custom else ""
+    lines.append(f'  {f.resolved_id} "{f.name}" — {schema_type}{custom_suffix}')
+
+    if f.allowedValues:
+        values = []
+        for v in f.allowedValues[:30]:
+            if isinstance(v, dict):
+                values.append(v.get("name", v.get("value", json.dumps(v))))
+            else:
+                values.append(str(v))
+        suffix = (
+            f", ... ({len(f.allowedValues)} total)" if len(f.allowedValues) > 30 else ""
+        )
+        lines.append(f"    Allowed values: {', '.join(values)}{suffix}")
+
+    if f.defaultValue is not None:
+        if isinstance(f.defaultValue, dict):
+            dv = f.defaultValue.get(
+                "name", f.defaultValue.get("value", json.dumps(f.defaultValue))
+            )
+        else:
+            dv = str(f.defaultValue)
+        lines.append(f"    Default: {dv}")
+
+    return lines