runspec-jira 0.1.0__tar.gz

runspec_jira-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-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `runspec-jira` are documented here.
+
+## [0.1.0] — 2026-08-07
+
+Initial release. A full-featured `jira` runnable ported from the Atlassian MCP
+server (sooperset/mcp-atlassian) onto `atlassian-python-api`, covering Jira
+Software/Core **and** Service Desk (JSM) on Cloud and Server/Data Center. Thin
+wrapper over `runspec-jira-core`.
+
+- One runnable, `jira`, with a verb per tool; `runspec serve` re-expands each into
+  a leaf MCP tool (`jira_get-issue`, …). Reads are `autonomous`, writes `confirm`.
+- Verbs: issues (get/create/update/assign/delete), search (`search` JQL,
+  `get-project-issues`), transitions (list/transition), comments (add/edit), links
+  (link types, issue link, epic link, remote link, remove), worklog (get/add),
+  projects (get-all/search/components/issue-types/create-fields), field discovery
+  (`search-fields`), users (profile/assignable), watchers (get/add/remove), and
+  service desk (`list-request-types`, `list-request-type-fields`, `raise-request`,
+  `get-request`).
+- Auth is env-var driven (`JIRA_URL` + `JIRA_PERSONAL_TOKEN` or
+  `JIRA_USERNAME`/`JIRA_API_TOKEN`), with `JIRA_<ENV>_*` prefixes selected by the
+  global `--env`. Cloud vs Server/DC via `JIRA_CLOUD` or a `.atlassian.net` host.
+- JSON-object arguments (`--additional-fields`, `--fields`, `--visibility`,
+  `--worklog-json`, `--field-values`) are passed as strings and parsed in the core.
+
+The existing `runspec-jsm` package is unchanged; it remains the narrow
+"one runnable per project" JSM service-desk option. Deferred here: attachments/
+media, images, OAuth 2.0, transition-by-id with screen fields, cross-project move.

runspec_jira-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-jira
+Version: 0.1.0
+Summary: Full-featured Jira runnable for runspec — issues, search, transitions, links, worklogs, projects, users, and service desk (Cloud + Server/Data Center)
+Requires-Python: >=3.10
+Requires-Dist: runspec-jira-core>=0.1.0
+Requires-Dist: runspec>=0.44.0
+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-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-jira"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Full-featured Jira runnable for runspec — issues, search, transitions, links, worklogs, projects, users, and service desk (Cloud + Server/Data Center)"
+dependencies = [
+    # 0.44.0 surfaces inherited args (the global --env) on each leaf subcommand's
+    # MCP tool via `runspec serve`.
+    "runspec>=0.44.0",
+    "runspec-jira-core>=0.1.0",
+]
+
+[project.scripts]
+# Entry point name MUST match the runnable name in runspec.toml (`jira`).
+jira = "runspec_jira.cli:main"
+
+[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-0.1.0/runspec_jira/__init__.py

@@ -0,0 +1,87 @@
+"""runspec-jira — a full-featured Jira runnable (issues, search, transitions,
+links, worklogs, projects, users, watchers, and service desk) over
+``atlassian-python-api``, on Cloud and Server/Data Center.
+
+The logic lives in the dependency-light ``runspec-jira-core``; this package is the
+thin ``jira`` runnable wrapper. The core helpers are re-exported here for
+back-compat so ``from runspec_jira import get_issue`` works without naming the
+core package.
+"""
+
+from runspec_jira_core import (
+    JiraConfig,
+    JiraError,
+    add_comment,
+    add_watcher,
+    add_worklog,
+    assign_issue,
+    config_from_env,
+    create_customer_request,
+    create_issue,
+    create_issue_link,
+    create_remote_issue_link,
+    delete_issue,
+    edit_comment,
+    get_all_projects,
+    get_create_fields,
+    get_issue,
+    get_link_types,
+    get_project_components,
+    get_project_issue_types,
+    get_project_issues,
+    get_request,
+    get_user_profile,
+    get_watchers,
+    get_worklog,
+    jql_search,
+    link_to_epic,
+    list_request_type_fields,
+    list_request_types,
+    list_transitions,
+    remove_issue_link,
+    remove_watcher,
+    search_assignable_users,
+    search_fields,
+    search_projects,
+    transition_issue,
+    update_issue,
+)
+
+__all__ = [
+    "JiraConfig",
+    "JiraError",
+    "config_from_env",
+    "get_issue",
+    "create_issue",
+    "update_issue",
+    "assign_issue",
+    "delete_issue",
+    "jql_search",
+    "get_project_issues",
+    "list_transitions",
+    "transition_issue",
+    "add_comment",
+    "edit_comment",
+    "get_link_types",
+    "create_issue_link",
+    "link_to_epic",
+    "create_remote_issue_link",
+    "remove_issue_link",
+    "get_worklog",
+    "add_worklog",
+    "get_all_projects",
+    "search_projects",
+    "get_project_components",
+    "get_project_issue_types",
+    "get_create_fields",
+    "search_fields",
+    "get_user_profile",
+    "search_assignable_users",
+    "get_watchers",
+    "add_watcher",
+    "remove_watcher",
+    "list_request_types",
+    "list_request_type_fields",
+    "create_customer_request",
+    "get_request",
+]

runspec_jira-0.1.0/runspec_jira/cli.py

@@ -0,0 +1,211 @@
+"""cli.py — the ``jira`` entry point.
+
+One binary, a verb per Jira tool. ``rs.parse("jira")`` resolves the subcommand and
+its args; we build a :class:`JiraConfig` from the environment (scoped by the global
+``--env``), unpack each ``.value`` at the boundary, and call the matching
+:mod:`runspec_jira_core` helper. JSON-object arguments travel as raw strings and
+are parsed inside the core op.
+
+Failures (the core :class:`JiraError` and arg-shape ``ValueError``s) become a JSON
+``{"error": ...}`` payload + a non-zero exit.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import runspec as rs
+from runspec_jira_core import (
+    JiraConfig,
+    JiraError,
+    add_comment,
+    add_watcher,
+    add_worklog,
+    assign_issue,
+    config_from_env,
+    create_customer_request,
+    create_issue,
+    create_issue_link,
+    create_remote_issue_link,
+    delete_issue,
+    edit_comment,
+    get_all_projects,
+    get_create_fields,
+    get_issue,
+    get_link_types,
+    get_project_components,
+    get_project_issue_types,
+    get_project_issues,
+    get_request,
+    get_user_profile,
+    get_watchers,
+    get_worklog,
+    jql_search,
+    link_to_epic,
+    list_request_type_fields,
+    list_request_types,
+    list_transitions,
+    remove_issue_link,
+    remove_watcher,
+    search_assignable_users,
+    search_fields,
+    search_projects,
+    transition_issue,
+    update_issue,
+)
+
+
+def _emit(payload: Any) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _dispatch(spec: rs.RunSpec, config: JiraConfig) -> Any:
+    """Run the active verb against ``config``, unpacking only its declared args."""
+    command = spec.runspec_command
+
+    # ── issues ──
+    if command == "get-issue":
+        return get_issue(config, spec.key.value, fields=spec.fields.value or None, expand=spec.expand.value)
+    if command == "create-issue":
+        return create_issue(
+            config,
+            spec.project.value,
+            spec.summary.value,
+            spec.issue_type.value,
+            description=spec.description.value,
+            additional_fields=spec.additional_fields.value,
+        )
+    if command == "update-issue":
+        return update_issue(config, spec.key.value, fields_json=spec.fields.value)
+    if command == "assign-issue":
+        return assign_issue(config, spec.key.value, spec.assignee.value)
+    if command == "delete-issue":
+        return delete_issue(config, spec.key.value, delete_subtasks=spec.delete_subtasks.value)
+
+    # ── search ──
+    if command == "search":
+        return jql_search(
+            config,
+            spec.jql.value,
+            fields=spec.fields.value or None,
+            start=spec.start.value,
+            limit=spec.limit.value,
+            expand=spec.expand.value,
+        )
+    if command == "get-project-issues":
+        return get_project_issues(config, spec.project_key.value, limit=spec.limit.value)
+
+    # ── transitions ──
+    if command == "list-transitions":
+        return list_transitions(config, spec.key.value)
+    if command == "transition-issue":
+        return transition_issue(config, spec.key.value, status=spec.status.value, fields_json=spec.fields.value)
+
+    # ── comments ──
+    if command == "add-comment":
+        return add_comment(config, spec.key.value, spec.body.value, visibility_json=spec.visibility.value)
+    if command == "edit-comment":
+        return edit_comment(config, spec.key.value, spec.comment_id.value, spec.body.value)
+
+    # ── links ──
+    if command == "get-link-types":
+        return get_link_types(config)
+    if command == "create-issue-link":
+        return create_issue_link(
+            config,
+            spec.link_type.value,
+            spec.inward_issue.value,
+            spec.outward_issue.value,
+            comment=spec.comment.value,
+        )
+    if command == "link-to-epic":
+        return link_to_epic(config, spec.issue_key.value, spec.epic_key.value, epic_link_field=spec.epic_link_field.value)
+    if command == "create-remote-issue-link":
+        return create_remote_issue_link(
+            config,
+            spec.issue_key.value,
+            spec.url.value,
+            spec.title.value,
+            relationship=spec.relationship.value,
+        )
+    if command == "remove-issue-link":
+        return remove_issue_link(config, spec.link_id.value)
+
+    # ── worklog ──
+    if command == "get-worklog":
+        return get_worklog(config, spec.key.value)
+    if command == "add-worklog":
+        return add_worklog(
+            config,
+            spec.key.value,
+            time_sec=spec.time_sec.value,
+            started=spec.started.value,
+            comment=spec.comment.value,
+            worklog_json=spec.worklog_json.value,
+        )
+
+    # ── projects ──
+    if command == "get-all-projects":
+        return get_all_projects(config)
+    if command == "search-projects":
+        return search_projects(config, spec.query.value)
+    if command == "get-project-components":
+        return get_project_components(config, spec.project_key.value)
+    if command == "get-project-issue-types":
+        return get_project_issue_types(config, spec.project_key.value)
+    if command == "get-create-fields":
+        return get_create_fields(config, spec.project_key.value)
+
+    # ── fields ──
+    if command == "search-fields":
+        return search_fields(config, query=spec.query.value)
+
+    # ── users ──
+    if command == "get-user-profile":
+        return get_user_profile(config, username=spec.username.value, account_id=spec.account_id.value, key=spec.key.value)
+    if command == "search-assignable-users":
+        return search_assignable_users(config, spec.project_key.value, start=spec.start.value, limit=spec.limit.value)
+
+    # ── watchers ──
+    if command == "get-watchers":
+        return get_watchers(config, spec.key.value)
+    if command == "add-watcher":
+        return add_watcher(config, spec.key.value, spec.user.value)
+    if command == "remove-watcher":
+        return remove_watcher(config, spec.key.value, user=spec.user.value, account_id=spec.account_id.value)
+
+    # ── service desk ──
+    if command == "list-request-types":
+        return list_request_types(config, service_desk_id=spec.service_desk_id.value)
+    if command == "list-request-type-fields":
+        return list_request_type_fields(config, spec.request_type_id.value, service_desk_id=spec.service_desk_id.value)
+    if command == "raise-request":
+        return create_customer_request(
+            config,
+            spec.request_type_id.value,
+            spec.field_values.value,
+            service_desk_id=spec.service_desk_id.value,
+            raise_on_behalf_of=spec.raise_on_behalf_of.value,
+        )
+    if command == "get-request":
+        return get_request(config, spec.issue_id_or_key.value)
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `jira --help`")  # pragma: no cover
+
+
+def main() -> None:
+    spec = rs.parse("jira")
+    try:
+        config = config_from_env(env=spec.env.value)
+        result = _dispatch(spec, config)
+    except (JiraError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()

runspec_jira-0.1.0/runspec_jira/runspec.toml

@@ -0,0 +1,301 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-jira — a full-featured Jira runnable ported from the Atlassian MCP
+# server (sooperset/mcp-atlassian), onto atlassian-python-api.
+#
+# One runnable, `jira`, with a verb per tool. `runspec serve` re-expands each
+# verb into its own leaf MCP tool (jira_get-issue, jira_create-issue, …), so a
+# runspec-console agent calls them individually — over SSH on any fleet host,
+# with no second server process.
+#
+# Covers Jira Software/Core AND Service Desk (JSM), on Cloud and Server/Data
+# Center. Auth is env-var driven:
+#   JIRA_URL + (JIRA_PERSONAL_TOKEN  |  JIRA_USERNAME + JIRA_API_TOKEN)
+# Per-environment overrides use a JIRA_<ENV>_ prefix (e.g. JIRA_UAT_URL),
+# selected with the global --env (dev/uat/prod) arg. Cloud vs Server/DC is set
+# by JIRA_CLOUD, else inferred from a .atlassian.net host.
+#
+# Reads are autonomous; writes require confirmation. JSON-object arguments
+# (--additional-fields, --fields, --visibility, --worklog-json, --field-values)
+# are passed as strings and parsed by the runnable.
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+[jira]
+description = "Query and manipulate Jira issues, projects, and service-desk requests (Cloud or Server/Data Center)"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "jira get-issue --key PROJ-1", description = "Fetch a single issue"},
+  {cmd = "jira search --jql 'assignee = currentUser() AND statusCategory != Done'", description = "Run a JQL search"},
+  {cmd = "jira create-issue --project PROJ --summary 'Fix login' --issue-type Bug", description = "Create an issue"},
+  {cmd = "jira transition-issue --key PROJ-1 --status Done", description = "Move an issue to a status"},
+  {cmd = "jira list-request-types --service-desk-id 5", description = "List a service desk's request types"},
+]
+
+# ── global args (inherited by every verb) ──────────────────────────────────
+[jira.args]
+env = {type = "choice", options = ["dev", "uat", "prod"], short = "-e", required = false, description = "Target environment (selects JIRA_<ENV>_* vars, falling back to JIRA_*)"}
+
+# ── issues ─────────────────────────────────────────────────────────────────
+
+[jira.commands.get-issue]
+description = "Fetch a single issue by key, optionally limiting fields or expanding sections"
+autonomy = "autonomous"
+[jira.commands.get-issue.args]
+key = {type = "str", required = true, description = "Issue key, e.g. PROJ-123"}
+fields = {type = "str", multiple = true, required = false, description = "Restrict to these fields (repeat --fields)"}
+expand = {type = "str", required = false, description = "Comma-separated expand sections (e.g. changelog,renderedFields)"}
+
+[jira.commands.create-issue]
+description = "Create an issue in a project. Extra/custom fields go through --additional-fields as a JSON object."
+autonomy = "confirm"
+[jira.commands.create-issue.args]
+project = {type = "str", required = true, description = "Project key"}
+summary = {type = "str", required = true, description = "Issue summary"}
+issue-type = {type = "str", required = true, description = "Issue type name, e.g. Bug, Task, Story"}
+description = {type = "str", required = false, description = "Issue description (wiki markup on DC; plain text on Cloud)"}
+additional-fields = {type = "str", required = false, description = "JSON object of extra fields merged into the create payload, e.g. '{\"labels\":[\"x\"],\"priority\":{\"name\":\"High\"}}'"}
+
+[jira.commands.update-issue]
+description = "Update an issue's fields from a JSON object"
+autonomy = "confirm"
+[jira.commands.update-issue.args]
+key = {type = "str", required = true, description = "Issue key"}
+fields = {type = "str", required = true, description = "JSON object of fields to set, e.g. '{\"summary\":\"New title\"}'"}
+
+[jira.commands.assign-issue]
+description = "Assign an issue to a user (accountId on Cloud, username on Server/DC)"
+autonomy = "confirm"
+[jira.commands.assign-issue.args]
+key = {type = "str", required = true, description = "Issue key"}
+assignee = {type = "str", required = true, description = "Cloud accountId or Server/DC username"}
+
+[jira.commands.delete-issue]
+description = "Delete an issue (and, by default, its subtasks)"
+autonomy = "confirm"
+[jira.commands.delete-issue.args]
+key = {type = "str", required = true, description = "Issue key"}
+delete-subtasks = {type = "flag", default = true, description = "Also delete subtasks (default true)"}
+
+# ── search ─────────────────────────────────────────────────────────────────
+
+[jira.commands.search]
+description = "Search issues with JQL; returns one page (pass --start/--limit to page)"
+autonomy = "autonomous"
+[jira.commands.search.args]
+jql = {type = "str", required = true, description = "JQL query string"}
+fields = {type = "str", multiple = true, required = false, description = "Fields to return (repeat --fields; default all)"}
+limit = {type = "int", default = 50, description = "Max results (maxResults)"}
+start = {type = "int", default = 0, description = "Pagination offset (startAt)"}
+expand = {type = "str", required = false, description = "Comma-separated expand sections"}
+
+[jira.commands.get-project-issues]
+description = "List a project's issues, newest first (one page)"
+autonomy = "autonomous"
+[jira.commands.get-project-issues.args]
+project-key = {type = "str", required = true, description = "Project key"}
+limit = {type = "int", default = 50, description = "Max results"}
+
+# ── transitions ────────────────────────────────────────────────────────────
+
+[jira.commands.list-transitions]
+description = "List the workflow transitions available from an issue's current status"
+autonomy = "autonomous"
+[jira.commands.list-transitions.args]
+key = {type = "str", required = true, description = "Issue key"}
+
+[jira.commands.transition-issue]
+description = "Move an issue to a target status by name (resolves the workflow transition automatically)"
+autonomy = "confirm"
+[jira.commands.transition-issue.args]
+key = {type = "str", required = true, description = "Issue key"}
+status = {type = "str", required = true, description = "Target status name, e.g. 'In Progress', Done"}
+fields = {type = "str", required = false, description = "JSON object of fields required by the transition screen"}
+
+# ── comments ───────────────────────────────────────────────────────────────
+
+[jira.commands.add-comment]
+description = "Add a comment to an issue"
+autonomy = "confirm"
+[jira.commands.add-comment.args]
+key = {type = "str", required = true, description = "Issue key"}
+body = {type = "str", required = true, description = "Comment body"}
+visibility = {type = "str", required = false, description = "JSON object restricting visibility, e.g. '{\"type\":\"role\",\"value\":\"Administrators\"}'"}
+
+[jira.commands.edit-comment]
+description = "Edit an existing comment on an issue"
+autonomy = "confirm"
+[jira.commands.edit-comment.args]
+key = {type = "str", required = true, description = "Issue key"}
+comment-id = {type = "str", required = true, description = "Comment id"}
+body = {type = "str", required = true, description = "New comment body"}
+
+# ── links ──────────────────────────────────────────────────────────────────
+
+[jira.commands.get-link-types]
+description = "List the issue link types available on the instance (e.g. Blocks, Relates)"
+autonomy = "autonomous"
+
+[jira.commands.create-issue-link]
+description = "Link two issues with a named link type"
+autonomy = "confirm"
+[jira.commands.create-issue-link.args]
+link-type = {type = "str", required = true, description = "Link type name, e.g. Blocks"}
+inward-issue = {type = "str", required = true, description = "The inward issue key (e.g. the blocker)"}
+outward-issue = {type = "str", required = true, description = "The outward issue key (e.g. the blocked)"}
+comment = {type = "str", required = false, description = "Optional comment to add with the link"}
+
+[jira.commands.link-to-epic]
+description = "Link an issue to an epic (Cloud parent / Server/DC Epic Link field)"
+autonomy = "confirm"
+[jira.commands.link-to-epic.args]
+issue-key = {type = "str", required = true, description = "Issue to link"}
+epic-key = {type = "str", required = true, description = "Epic issue key"}
+epic-link-field = {type = "str", required = false, description = "Force a specific Epic Link custom field id (customfield_XXXXX)"}
+
+[jira.commands.create-remote-issue-link]
+description = "Attach a remote (web) link to an issue"
+autonomy = "confirm"
+[jira.commands.create-remote-issue-link.args]
+issue-key = {type = "str", required = true, description = "Issue key"}
+url = {type = "str", required = true, description = "The web URL to link to"}
+title = {type = "str", required = true, description = "Link title"}
+relationship = {type = "str", required = false, description = "Optional relationship label"}
+
+[jira.commands.remove-issue-link]
+description = "Remove an issue link by its id"
+autonomy = "confirm"
+[jira.commands.remove-issue-link.args]
+link-id = {type = "str", required = true, description = "Issue link id"}
+
+# ── worklog ────────────────────────────────────────────────────────────────
+
+[jira.commands.get-worklog]
+description = "Return an issue's work log entries"
+autonomy = "autonomous"
+[jira.commands.get-worklog.args]
+key = {type = "str", required = true, description = "Issue key"}
+
+[jira.commands.add-worklog]
+description = "Log work on an issue (pass --time-sec, or a full --worklog-json object)"
+autonomy = "confirm"
+[jira.commands.add-worklog.args]
+key = {type = "str", required = true, description = "Issue key"}
+time-sec = {type = "int", required = false, description = "Time spent in seconds"}
+started = {type = "str", required = false, description = "Start time (ISO 8601, e.g. 2026-08-07T09:00:00.000+0000)"}
+comment = {type = "str", required = false, description = "Worklog comment"}
+worklog-json = {type = "str", required = false, description = "Full worklog JSON object (overrides the scalar args)"}
+
+# ── projects ───────────────────────────────────────────────────────────────
+
+[jira.commands.get-all-projects]
+description = "List every project visible to the configured credentials"
+autonomy = "autonomous"
+
+[jira.commands.search-projects]
+description = "Filter visible projects by a substring of name or key"
+autonomy = "autonomous"
+[jira.commands.search-projects.args]
+query = {type = "str", required = true, description = "Text to match against project name/key"}
+
+[jira.commands.get-project-components]
+description = "List a project's components"
+autonomy = "autonomous"
+[jira.commands.get-project-components.args]
+project-key = {type = "str", required = true, description = "Project key"}
+
+[jira.commands.get-project-issue-types]
+description = "List the issue types available when creating in a project"
+autonomy = "autonomous"
+[jira.commands.get-project-issue-types.args]
+project-key = {type = "str", required = true, description = "Project key"}
+
+[jira.commands.get-create-fields]
+description = "Return the create-screen field metadata for a project (the discovery step before create-issue --additional-fields)"
+autonomy = "autonomous"
+[jira.commands.get-create-fields.args]
+project-key = {type = "str", required = true, description = "Project key"}
+
+# ── fields ─────────────────────────────────────────────────────────────────
+
+[jira.commands.search-fields]
+description = "List fields, optionally filtered by a substring of name or id (find a custom field's id)"
+autonomy = "autonomous"
+[jira.commands.search-fields.args]
+query = {type = "str", required = false, description = "Text to match against field name/id"}
+
+# ── users ──────────────────────────────────────────────────────────────────
+
+[jira.commands.get-user-profile]
+description = "Fetch a user profile (Cloud: --account-id; Server/DC: --username or --key)"
+autonomy = "autonomous"
+[jira.commands.get-user-profile.args]
+username = {type = "str", required = false, description = "Server/DC username"}
+account-id = {type = "str", required = false, description = "Cloud accountId"}
+key = {type = "str", required = false, description = "Server/DC user key"}
+
+[jira.commands.search-assignable-users]
+description = "List users assignable to issues in a project (one page)"
+autonomy = "autonomous"
+[jira.commands.search-assignable-users.args]
+project-key = {type = "str", required = true, description = "Project key"}
+start = {type = "int", default = 0, description = "Pagination offset"}
+limit = {type = "int", default = 50, description = "Max results"}
+
+# ── watchers ───────────────────────────────────────────────────────────────
+
+[jira.commands.get-watchers]
+description = "List the watchers of an issue"
+autonomy = "autonomous"
+[jira.commands.get-watchers.args]
+key = {type = "str", required = true, description = "Issue key"}
+
+[jira.commands.add-watcher]
+description = "Add a watcher to an issue (username on Server/DC, accountId on Cloud)"
+autonomy = "confirm"
+[jira.commands.add-watcher.args]
+key = {type = "str", required = true, description = "Issue key"}
+user = {type = "str", required = true, description = "Username (Server/DC) or accountId (Cloud)"}
+
+[jira.commands.remove-watcher]
+description = "Remove a watcher (Cloud: --account-id; Server/DC: --user)"
+autonomy = "confirm"
+[jira.commands.remove-watcher.args]
+key = {type = "str", required = true, description = "Issue key"}
+user = {type = "str", required = false, description = "Server/DC username"}
+account-id = {type = "str", required = false, description = "Cloud accountId"}
+
+# ── service desk (JSM) ─────────────────────────────────────────────────────
+
+[jira.commands.list-request-types]
+description = "List the request types offered by a service desk"
+autonomy = "autonomous"
+[jira.commands.list-request-types.args]
+service-desk-id = {type = "str", required = false, description = "Service desk id (falls back to JIRA_SERVICE_DESK_ID)"}
+
+[jira.commands.list-request-type-fields]
+description = "List the fields a request type expects (feeds raise-request)"
+autonomy = "autonomous"
+[jira.commands.list-request-type-fields.args]
+request-type-id = {type = "str", required = true, description = "Request type id"}
+service-desk-id = {type = "str", required = false, description = "Service desk id (falls back to JIRA_SERVICE_DESK_ID)"}
+
+[jira.commands.raise-request]
+description = "Raise a customer request. --field-values is a JSON object keyed by fieldId (see list-request-type-fields)."
+autonomy = "confirm"
+[jira.commands.raise-request.args]
+request-type-id = {type = "str", required = true, description = "Request type id"}
+field-values = {type = "str", required = true, description = "JSON object of fieldId: value, e.g. '{\"summary\":\"Laptop broken\"}'"}
+service-desk-id = {type = "str", required = false, description = "Service desk id (falls back to JIRA_SERVICE_DESK_ID)"}
+raise-on-behalf-of = {type = "str", required = false, description = "Raise the request on behalf of this reporter"}
+
+[jira.commands.get-request]
+description = "Fetch a customer request by issue id or key"
+autonomy = "autonomous"
+[jira.commands.get-request.args]
+issue-id-or-key = {type = "str", required = true, description = "Request issue id or key"}

runspec_jira-0.1.0/tests/test_cli.py

@@ -0,0 +1,117 @@
+"""Wrapper logic: real parsed spec → `_dispatch` → core helper, with the core's
+atlassian client faked (no real SDK calls), plus the main() error path."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+from runspec.testing import ParseHarness
+from runspec_jira_core import JiraConfig
+from runspec_jira_core import client as core_client
+
+from runspec_jira import cli
+
+SPEC = Path(__file__).parent.parent / "runspec_jira" / "runspec.toml"
+CLOUD = JiraConfig(url="https://acme.atlassian.net", cloud=True, username="me@x.com", api_token="tok", service_desk_id="5")
+DC = JiraConfig(url="https://jira.corp", cloud=False, personal_token="pat")
+
+
+class FakeClient:
+    def __init__(self, returns: dict[str, Any] | None = None):
+        self.calls: list[tuple[str, tuple, dict]] = []
+        self._returns = returns or {}
+
+    def __getattr__(self, name: str):
+        def method(*args: Any, **kwargs: Any) -> Any:
+            self.calls.append((name, args, kwargs))
+            return self._returns.get(name)
+
+        return method
+
+    def last(self, name: str) -> tuple[tuple, dict]:
+        for called, args, kwargs in reversed(self.calls):
+            if called == name:
+                return args, kwargs
+        raise AssertionError(f"{name} not called; saw {[c[0] for c in self.calls]}")
+
+
+@pytest.fixture
+def fake(monkeypatch):
+    jira = FakeClient()
+    sd = FakeClient()
+    monkeypatch.setattr(core_client, "Jira", lambda **kw: jira)
+    monkeypatch.setattr(core_client, "ServiceDesk", lambda **kw: sd)
+    return jira, sd
+
+
+def _harness() -> ParseHarness:
+    return ParseHarness(script_name="jira", config_path=SPEC)
+
+
+def test_dispatch_get_issue(fake) -> None:
+    jira, _ = fake
+    jira._returns["get_issue"] = {"key": "PROJ-1"}
+    h = _harness()
+    spec = h.expect_ok(["get-issue", "--key", "PROJ-1", "--fields", "summary"])
+    result = cli._dispatch(spec, CLOUD)
+    h.close()
+    assert result == {"key": "PROJ-1"}
+    args, kwargs = jira.last("get_issue")
+    assert args == ("PROJ-1",)
+    assert kwargs["fields"] == "summary"
+
+
+def test_dispatch_create_issue_merges_json(fake) -> None:
+    jira, _ = fake
+    h = _harness()
+    spec = h.expect_ok(["create-issue", "--project", "P", "--summary", "s", "--issue-type", "Bug", "--additional-fields", '{"labels":["x"]}'])
+    cli._dispatch(spec, CLOUD)
+    h.close()
+    _, kwargs = jira.last("create_issue")
+    assert kwargs["fields"]["labels"] == ["x"]
+    assert kwargs["fields"]["project"] == {"key": "P"}
+
+
+def test_dispatch_transition_issue(fake) -> None:
+    jira, _ = fake
+    h = _harness()
+    spec = h.expect_ok(["transition-issue", "--key", "PROJ-1", "--status", "Done"])
+    cli._dispatch(spec, CLOUD)
+    h.close()
+    args, _ = jira.last("set_issue_status")
+    assert args == ("PROJ-1", "Done")
+
+
+def test_dispatch_raise_request_uses_servicedesk(fake) -> None:
+    _, sd = fake
+    h = _harness()
+    spec = h.expect_ok(["raise-request", "--request-type-id", "17", "--field-values", '{"summary":"x"}'])
+    cli._dispatch(spec, CLOUD)
+    h.close()
+    args, kwargs = sd.last("create_customer_request")
+    assert args[0] == "5"  # falls back to config.service_desk_id
+    assert args[1] == "17"
+    assert args[2] == {"summary": "x"}
+
+
+def test_dispatch_bad_json_raises_jira_error(fake) -> None:
+    h = _harness()
+    spec = h.expect_ok(["update-issue", "--key", "PROJ-1", "--fields", "{oops"])
+    with pytest.raises(Exception, match="not valid JSON"):
+        cli._dispatch(spec, CLOUD)
+    h.close()
+
+
+def test_main_missing_config_emits_error(monkeypatch, capsys) -> None:
+    for var in ("JIRA_URL", "JIRA_USERNAME", "JIRA_API_TOKEN", "JIRA_PERSONAL_TOKEN", "JIRA_ENV"):
+        monkeypatch.delenv(var, raising=False)
+    h = _harness()
+    spec = h.expect_ok(["get-issue", "--key", "PROJ-1"])
+    h.close()
+    monkeypatch.setattr(cli.rs, "parse", lambda name: spec)
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["kind"] == "JiraError"

runspec_jira-0.1.0/tests/test_spec.py

@@ -0,0 +1,98 @@
+"""Wiring / parsing tests for the `jira` runnable — no mocks, real spec."""
+
+from pathlib import Path
+
+from runspec.testing import ParseHarness
+
+SPEC = Path(__file__).parent.parent / "runspec_jira" / "runspec.toml"
+
+# One value per arg name, reused across every verb that declares it.
+VALUES = {
+    "key": "PROJ-1",
+    "project": "PROJ",
+    "project-key": "PROJ",
+    "summary": "Fix login",
+    "issue-type": "Bug",
+    "fields": "{}",  # required JSON string on update-issue; harmless elsewhere
+    "assignee": "acc-1",
+    "jql": "project = PROJ",
+    "status": "Done",
+    "body": "a comment",
+    "comment-id": "10010",
+    "link-type": "Blocks",
+    "inward-issue": "PROJ-1",
+    "outward-issue": "PROJ-2",
+    "issue-key": "PROJ-1",
+    "epic-key": "EPIC-1",
+    "url": "https://example.com",
+    "title": "Docs",
+    "link-id": "10100",
+    "query": "epic",
+    "user": "jbloggs",
+    "request-type-id": "17",
+    "field-values": "{}",
+    "issue-id-or-key": "SD-1",
+}
+
+
+def _harness() -> ParseHarness:
+    return ParseHarness(script_name="jira", config_path=SPEC)
+
+
+def test_smoke_all_verbs() -> None:
+    h = _harness()
+    done = h.smoke(values=VALUES)
+    # Guard against accidentally checking nothing (34 verbs → many checks).
+    assert len(done) > 60
+    h.close()
+
+
+def test_global_env_choice_inherited() -> None:
+    h = _harness()
+    spec = h.expect_ok(["--env", "uat", "get-issue", "--key", "PROJ-1"])
+    assert spec.env.value == "uat"
+    assert spec.runspec_command == "get-issue"
+    h.close()
+
+
+def test_bad_env_choice_rejected() -> None:
+    h = _harness()
+    h.expect_exit(["--env", "staging", "get-issue", "--key", "PROJ-1"], contains="env")
+    h.close()
+
+
+def test_fields_multiple_collects_list() -> None:
+    h = _harness()
+    spec = h.expect_ok(["get-issue", "--key", "PROJ-1", "--fields", "summary", "--fields", "status"])
+    assert spec.fields.value == ["summary", "status"]
+    h.close()
+
+
+def test_search_limit_defaults_and_coerces() -> None:
+    h = _harness()
+    spec = h.expect_ok(["search", "--jql", "project = PROJ"])
+    assert spec.limit.value == 50
+    assert spec.start.value == 0
+    spec2 = h.expect_ok(["search", "--jql", "x", "--limit", "5"])
+    assert spec2.limit.value == 5
+    assert isinstance(spec2.limit.value, int)
+    h.close()
+
+
+def test_delete_subtasks_flag_defaults_true() -> None:
+    h = _harness()
+    spec = h.expect_ok(["delete-issue", "--key", "PROJ-1"])
+    assert spec.delete_subtasks.value is True
+    h.close()
+
+
+def test_missing_required_key_rejected() -> None:
+    h = _harness()
+    h.expect_exit(["get-issue"], contains="key")
+    h.close()
+
+
+def test_require_command_enforced() -> None:
+    h = _harness()
+    h.expect_exit([])
+    h.close()