runspec-jira-core 0.1.0__tar.gz

runspec_jira_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_jira_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `runspec-jira-core` are documented here.
+
+## [0.1.0] — 2026-08-07
+
+Initial release. Pure-Python Jira Software/Core + Service Desk helpers over
+`atlassian-python-api` — the importable core behind `runspec-jira`. No `runspec`
+dependency, no `runspec.toml`, no entry points (surfaces zero runnables).
+
+- `JiraConfig` + `config_from_env(env=None)` — env-var auth (`JIRA_URL`,
+  `JIRA_USERNAME`/`JIRA_API_TOKEN` for Cloud/DC basic, `JIRA_PERSONAL_TOKEN` for
+  DC PAT) with `JIRA_<ENV>_*` prefixes selected by `--env dev|uat|prod`. Cloud vs
+  Server/Data Center resolved via `JIRA_CLOUD` or a `.atlassian.net` host.
+- `build_client` / `build_servicedesk` construct `atlassian.Jira` /
+  `atlassian.ServiceDesk`, picking exactly one auth mode.
+- Operation helpers grouped by area: issues (get/create/update/assign/delete),
+  search (`jql_search`, `get_project_issues`), transitions, comments, links
+  (issue links, epic link, remote link), worklog, projects (discovery +
+  create-field metadata), users, field discovery, watchers, and service desk (request
+  types, request-type fields, create customer request, get request).
+- `translate_errors` surfaces the SDK's `requests` exceptions as `JiraError`
+  carrying Jira's own error message; `parse_json_arg` parses JSON-string args.
+
+Deferred: attachments/media, images, OAuth 2.0, transition-by-id with screen
+fields, cross-project issue move.

runspec_jira_core-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: runspec-jira-core
+Version: 0.1.0
+Summary: Pure-Python Jira + Service Desk helpers (over atlassian-python-api) — the importable core behind runspec-jira (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Requires-Dist: atlassian-python-api>=3.41
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_jira_core-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-jira-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python Jira + Service Desk helpers (over atlassian-python-api) — the importable core behind runspec-jira (no runspec dependency, no runnables)"
+dependencies = [
+    "atlassian-python-api>=3.41",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_jira_core-0.1.0/runspec_jira_core/__init__.py

@@ -0,0 +1,113 @@
+"""runspec-jira-core — Jira Software/Core + Service Desk helpers over atlassian-python-api.
+
+This package depends only on ``atlassian-python-api`` — it has **no dependency on
+runspec** and ships **no runspec.toml and no entry points**, so installing it
+exposes the helper functions for import without surfacing any runnables (it is
+invisible to ``runspec local`` / ``runspec serve`` discovery). ``runspec-jira``
+depends on it and wraps each helper as a verb of the ``jira`` runnable.
+
+Every operation takes an explicit :class:`JiraConfig` first argument, so a private
+(e.g. Nexus-hosted) wrapper package can inject credentials in code, bake in a
+default ``service_desk_id`` / ``project_key`` / ``env``, and build "one runnable
+per project" on top. Each function returns plain data and raises
+:class:`JiraError` on failure. Cloud and Server/Data Center are both supported.
+"""
+
+from runspec_jira_core.client import (
+    build_client,
+    build_servicedesk,
+    parse_json_arg,
+    translate_errors,
+)
+from runspec_jira_core.comments import add_comment, edit_comment
+from runspec_jira_core.config import VALID_ENVS, JiraConfig, config_from_env
+from runspec_jira_core.errors import JiraError
+from runspec_jira_core.fields import search_fields
+from runspec_jira_core.issues import (
+    assign_issue,
+    create_issue,
+    delete_issue,
+    get_issue,
+    update_issue,
+)
+from runspec_jira_core.links import (
+    create_issue_link,
+    create_remote_issue_link,
+    get_link_types,
+    link_to_epic,
+    remove_issue_link,
+)
+from runspec_jira_core.projects import (
+    get_all_projects,
+    get_create_fields,
+    get_project_components,
+    get_project_issue_types,
+    search_projects,
+)
+from runspec_jira_core.search import get_project_issues, jql_search
+from runspec_jira_core.servicedesk import (
+    create_customer_request,
+    get_request,
+    list_request_type_fields,
+    list_request_types,
+)
+from runspec_jira_core.transitions import list_transitions, transition_issue
+from runspec_jira_core.users import get_user_profile, search_assignable_users
+from runspec_jira_core.watchers import add_watcher, get_watchers, remove_watcher
+from runspec_jira_core.worklog import add_worklog, get_worklog
+
+__all__ = [
+    # config / client
+    "JiraConfig",
+    "JiraError",
+    "config_from_env",
+    "build_client",
+    "build_servicedesk",
+    "parse_json_arg",
+    "translate_errors",
+    "VALID_ENVS",
+    # issues
+    "get_issue",
+    "create_issue",
+    "update_issue",
+    "assign_issue",
+    "delete_issue",
+    # search
+    "jql_search",
+    "get_project_issues",
+    # transitions
+    "list_transitions",
+    "transition_issue",
+    # comments
+    "add_comment",
+    "edit_comment",
+    # links
+    "get_link_types",
+    "create_issue_link",
+    "link_to_epic",
+    "create_remote_issue_link",
+    "remove_issue_link",
+    # worklog
+    "get_worklog",
+    "add_worklog",
+    # projects
+    "get_all_projects",
+    "search_projects",
+    "get_project_components",
+    "get_project_issue_types",
+    "get_create_fields",
+    # fields
+    "search_fields",
+    # users
+    "get_user_profile",
+    "search_assignable_users",
+    # watchers
+    "get_watchers",
+    "add_watcher",
+    "remove_watcher",
+    # service desk
+    "list_request_types",
+    "list_request_type_fields",
+    "create_customer_request",
+    "get_request",
+]

runspec_jira_core-0.1.0/runspec_jira_core/client.py

@@ -0,0 +1,100 @@
+"""client.py — build ``atlassian-python-api`` clients + shared op helpers.
+
+``build_client`` / ``build_servicedesk`` turn a :class:`JiraConfig` into an
+``atlassian.Jira`` / ``atlassian.ServiceDesk`` instance, picking exactly one auth
+mode (Basic when username+api_token are set, else Bearer PAT) so the SDK never
+silently drops the PAT because Basic won.
+
+``@translate_errors`` wraps each operation so the SDK's ``requests`` exceptions
+surface as a :class:`JiraError` carrying Jira's own error message. ``parse_json_arg``
+parses the JSON-string arguments (create/update fields, comment visibility,
+worklog, service-desk field values) at the operation boundary.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import requests
+from atlassian import Jira, ServiceDesk
+
+from runspec_jira_core.config import JiraConfig
+from runspec_jira_core.errors import JiraError
+
+_T = TypeVar("_T")
+
+
+def _auth_kwargs(config: JiraConfig) -> dict[str, Any]:
+    base: dict[str, Any] = {"url": config.url, "cloud": config.cloud, "verify_ssl": config.verify_ssl}
+    if config.username and config.api_token:
+        base.update(username=config.username, password=config.api_token)
+    elif config.personal_token:
+        base.update(token=config.personal_token)
+    else:
+        raise JiraError("JiraConfig has no usable credentials (need personal_token or username+api_token)")
+    return base
+
+
+def build_client(config: JiraConfig) -> Jira:
+    """Construct an ``atlassian.Jira`` client for ``config``."""
+    return Jira(**_auth_kwargs(config))
+
+
+def build_servicedesk(config: JiraConfig) -> ServiceDesk:
+    """Construct an ``atlassian.ServiceDesk`` client for ``config`` (JSM verbs)."""
+    return ServiceDesk(**_auth_kwargs(config))
+
+
+def parse_json_arg(name: str, raw: str | None) -> Any:
+    """Parse a JSON-string CLI argument, or return ``None`` when unset.
+
+    Raises :class:`JiraError` (not a bare ``JSONDecodeError``) so the wrapper's
+    fixed catch tuple reports it as a clean ``{"error": ...}`` payload.
+    """
+    if raw is None or raw == "":
+        return None
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, TypeError) as exc:
+        raise JiraError(f"--{name} is not valid JSON: {exc}") from exc
+
+
+def _message(exc: requests.HTTPError) -> str:
+    """Extract a human-readable message from a Jira error response."""
+    resp = getattr(exc, "response", None)
+    if resp is None:
+        return f"Jira request failed: {exc}"
+    try:
+        body = resp.json()
+    except Exception:
+        return f"Jira {resp.status_code}: {resp.text[:500]}"
+    if isinstance(body, dict):
+        parts: list[str] = list(body.get("errorMessages") or [])
+        errors = body.get("errors")
+        if isinstance(errors, dict):
+            parts += [f"{k}: {v}" for k, v in errors.items()]
+        if parts:
+            return f"Jira {resp.status_code}: {'; '.join(map(str, parts))}"
+        # servicedeskapi / generic shape
+        message = body.get("errorMessage") or body.get("message")
+        if message:
+            return f"Jira {resp.status_code}: {message}"
+    return f"Jira {resp.status_code}: {str(body)[:500]}"
+
+
+def translate_errors(fn: Callable[..., _T]) -> Callable[..., _T]:
+    """Decorator: turn the SDK's ``requests`` exceptions into ``JiraError``."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> _T:
+        try:
+            return fn(*args, **kwargs)
+        except requests.HTTPError as exc:
+            raise JiraError(_message(exc)) from exc
+        except requests.RequestException as exc:
+            raise JiraError(f"Jira request failed: {exc}") from exc
+
+    return wrapper

runspec_jira_core-0.1.0/runspec_jira_core/comments.py

@@ -0,0 +1,28 @@
+"""comments.py — add and edit issue comments."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_jira_core.client import build_client, parse_json_arg, translate_errors
+from runspec_jira_core.config import JiraConfig
+
+
+@translate_errors
+def add_comment(
+    config: JiraConfig,
+    key: str,
+    body: str,
+    *,
+    visibility_json: str | None = None,
+) -> dict[str, Any]:
+    """Add a comment. ``visibility_json`` optionally restricts it, e.g.
+    ``{"type": "role", "value": "Administrators"}``."""
+    visibility = parse_json_arg("visibility", visibility_json)
+    return build_client(config).issue_add_comment(key, body, visibility=visibility)
+
+
+@translate_errors
+def edit_comment(config: JiraConfig, key: str, comment_id: str, body: str) -> dict[str, Any]:
+    """Edit an existing comment on an issue."""
+    return build_client(config).issue_edit_comment(key, comment_id, body)

runspec_jira_core-0.1.0/runspec_jira_core/config.py

@@ -0,0 +1,113 @@
+"""config.py — connection + identity for a Jira instance, from the environment.
+
+``JiraConfig`` carries everything the client builder needs. ``config_from_env``
+reads the ``JIRA_*`` family (with an optional ``JIRA_<ENV>_*`` prefix selected by
+``--env``), exactly like ``runspec-jsm`` / ``runspec-snow``. Every operation
+function in the package takes an explicit ``JiraConfig`` first argument, so a
+private (e.g. Nexus-hosted) wrapper can inject credentials in code, bake in a
+default ``service_desk_id`` / ``project_key`` / ``env``, and build "one runnable
+per project" on top.
+
+Cloud vs Server/Data Center is resolved once: an explicit ``JIRA_CLOUD`` wins,
+otherwise a ``.atlassian.net`` host is treated as Cloud and anything else as
+Server/DC. This drives both the ``atlassian.Jira(cloud=...)`` flag and the
+Cloud-vs-DC branches in a few operations (user identity, assignment, watchers).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from runspec_jira_core.errors import JiraError
+
+VALID_ENVS = ("dev", "uat", "prod")
+
+_FALSEY = ("0", "false", "no", "off")
+_TRUTHY = ("1", "true", "yes", "on")
+
+
+@dataclass
+class JiraConfig:
+    """Connection + identity for a Jira instance.
+
+    Provide EITHER ``personal_token`` (a Server/Data Center Personal Access Token,
+    sent as a Bearer token) OR ``username`` + ``api_token`` (Cloud email + API
+    token, or a Server/DC basic username + password). ``service_desk_id`` and
+    ``project_key`` are optional defaults a wrapper can bake in.
+    """
+
+    url: str
+    cloud: bool
+    username: str | None = None
+    api_token: str | None = None
+    personal_token: str | None = None
+    service_desk_id: str | None = None
+    project_key: str | None = None
+    verify_ssl: bool = True
+    env: str | None = None
+
+
+def _env_first(names: list[str]) -> str | None:
+    """Return the first non-empty environment variable among ``names``."""
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def _resolve_cloud(url: str, override: str | None) -> bool:
+    """Decide Cloud vs Server/DC: explicit override wins, else infer from host."""
+    if override is not None:
+        return override.strip().lower() in _TRUTHY
+    return ".atlassian.net" in url.lower()
+
+
+def config_from_env(env: str | None = None) -> JiraConfig:
+    """Build a :class:`JiraConfig` from environment variables.
+
+    When ``env`` (or the ``JIRA_ENV`` variable) selects dev/uat/prod, the
+    environment-prefixed variables are read first (e.g. ``JIRA_UAT_URL``), falling
+    back to the unprefixed ``JIRA_*`` family for single-instance setups. Raises
+    :class:`JiraError` with an actionable message when the env label is invalid,
+    the base URL is missing, or no usable credentials are configured.
+    """
+    env = env or os.environ.get("JIRA_ENV")
+    if env is not None:
+        env = env.lower()
+        if env not in VALID_ENVS:
+            raise JiraError(f"Invalid env {env!r} — expected one of {', '.join(VALID_ENVS)}")
+
+    def lookup(suffix: str) -> str | None:
+        names = []
+        if env:
+            names.append(f"JIRA_{env.upper()}_{suffix}")
+        names.append(f"JIRA_{suffix}")
+        return _env_first(names)
+
+    url = lookup("URL")
+    if not url:
+        hint = f"JIRA_{env.upper()}_URL" if env else "JIRA_URL"
+        raise JiraError(f"No base URL configured — set {hint}")
+
+    username = lookup("USERNAME")
+    api_token = lookup("API_TOKEN")
+    personal_token = lookup("PERSONAL_TOKEN")
+    if not personal_token and not (username and api_token):
+        raise JiraError("No credentials configured — set JIRA_PERSONAL_TOKEN (Server/DC PAT) or JIRA_USERNAME + JIRA_API_TOKEN (Cloud email + API token, or DC basic auth)")
+
+    verify = lookup("VERIFY_SSL")
+    verify_ssl = True if verify is None else verify.strip().lower() not in _FALSEY
+
+    return JiraConfig(
+        url=url.rstrip("/"),
+        cloud=_resolve_cloud(url, lookup("CLOUD")),
+        username=username,
+        api_token=api_token,
+        personal_token=personal_token,
+        service_desk_id=lookup("SERVICE_DESK_ID"),
+        project_key=lookup("PROJECT_KEY"),
+        verify_ssl=verify_ssl,
+        env=env,
+    )

runspec_jira_core-0.1.0/runspec_jira_core/errors.py

@@ -0,0 +1,13 @@
+"""errors.py — the exception type raised across runspec-jira-core.
+
+Every operation function raises :class:`JiraError` on configuration problems, bad
+JSON arguments, and non-2xx API responses (the underlying ``atlassian-python-api``
+raises ``requests`` exceptions, which the core translates into ``JiraError`` at the
+operation boundary so the wrapper catches one fixed type).
+"""
+
+from __future__ import annotations
+
+
+class JiraError(Exception):
+    """Raised on config problems, invalid arguments, and Jira API errors."""

runspec_jira_core-0.1.0/runspec_jira_core/fields.py

@@ -0,0 +1,19 @@
+"""fields.py — field discovery (find a custom field's id)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_jira_core.client import build_client, translate_errors
+from runspec_jira_core.config import JiraConfig
+
+
+@translate_errors
+def search_fields(config: JiraConfig, *, query: str | None = None) -> list[dict[str, Any]]:
+    """List fields, optionally filtered by a case-insensitive substring of name or
+    id (handy for finding a custom field's ``customfield_XXXXX`` id)."""
+    fields: Any = build_client(config).get_all_fields()
+    if query:
+        needle = query.lower()
+        return [f for f in fields if needle in str(f.get("name", "")).lower() or needle in str(f.get("id", "")).lower()]
+    return list(fields)

runspec_jira_core-0.1.0/runspec_jira_core/issues.py

@@ -0,0 +1,77 @@
+"""issues.py — issue read/create/update/assign/delete."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_jira_core.client import build_client, parse_json_arg, translate_errors
+from runspec_jira_core.config import JiraConfig
+from runspec_jira_core.errors import JiraError
+
+
+@translate_errors
+def get_issue(
+    config: JiraConfig,
+    key: str,
+    *,
+    fields: list[str] | None = None,
+    expand: str | None = None,
+) -> dict[str, Any]:
+    """Fetch a single issue by key. ``fields`` restricts the returned fields."""
+    fields_arg = ",".join(fields) if fields else None
+    return build_client(config).get_issue(key, fields=fields_arg, expand=expand)
+
+
+@translate_errors
+def create_issue(
+    config: JiraConfig,
+    project: str,
+    summary: str,
+    issue_type: str,
+    *,
+    description: str | None = None,
+    additional_fields: str | None = None,
+) -> dict[str, Any]:
+    """Create an issue. ``additional_fields`` is a JSON object merged into the
+    create payload (e.g. ``{"labels": ["x"], "priority": {"name": "High"}}``)."""
+    extra = parse_json_arg("additional-fields", additional_fields) or {}
+    if not isinstance(extra, dict):
+        raise JiraError("--additional-fields must be a JSON object")
+    fields: dict[str, Any] = {
+        "project": {"key": project},
+        "summary": summary,
+        "issuetype": {"name": issue_type},
+    }
+    if description:
+        fields["description"] = description
+    fields.update(extra)
+    return build_client(config).create_issue(fields=fields)
+
+
+@translate_errors
+def update_issue(config: JiraConfig, key: str, *, fields_json: str) -> dict[str, Any]:
+    """Update an issue from a JSON object of fields."""
+    fields = parse_json_arg("fields", fields_json)
+    if not isinstance(fields, dict):
+        raise JiraError("--fields must be a JSON object")
+    build_client(config).edit_issue(key, fields)
+    return {"key": key, "updated": True}
+
+
+@translate_errors
+def assign_issue(config: JiraConfig, key: str, assignee: str) -> dict[str, Any]:
+    """Assign an issue. On Cloud ``assignee`` is an accountId; on Server/DC it is a
+    username."""
+    client = build_client(config)
+    if config.cloud:
+        client.assign_issue(key, account_id=assignee)
+    else:
+        client.edit_issue(key, {"assignee": {"name": assignee}})
+    return {"key": key, "assignee": assignee}
+
+
+@translate_errors
+def delete_issue(config: JiraConfig, key: str, *, delete_subtasks: bool = True) -> dict[str, Any]:
+    """Delete an issue (and, by default, its subtasks)."""
+    build_client(config).delete_issue(key, delete_subtasks=delete_subtasks)
+    return {"key": key, "deleted": True}