runspec-confluence 0.1.0__py3-none-any.whl

runspec_confluence/__init__.py

@@ -0,0 +1,52 @@
+"""runspec-confluence — a Confluence runnable (pages, search, comments, labels,
+restrictions) over ``atlassian-python-api``, on Cloud and Server/Data Center.
+
+The logic lives in the dependency-light ``runspec-confluence-core``; this package
+is the thin ``confluence`` runnable wrapper. The core helpers are re-exported here
+for back-compat so ``from runspec_confluence import get_page`` works without naming
+the core package.
+"""
+
+from runspec_confluence_core import (
+    ConfluenceConfig,
+    ConfluenceError,
+    add_comment,
+    add_label,
+    config_from_env,
+    create_page,
+    delete_page,
+    get_comments,
+    get_labels,
+    get_page,
+    get_page_ancestors,
+    get_page_children,
+    get_page_history,
+    get_page_restrictions,
+    get_space,
+    get_space_pages,
+    move_page,
+    search,
+    update_page,
+)
+
+__all__ = [
+    "ConfluenceConfig",
+    "ConfluenceError",
+    "config_from_env",
+    "get_page",
+    "get_page_children",
+    "get_page_ancestors",
+    "create_page",
+    "update_page",
+    "delete_page",
+    "move_page",
+    "get_space_pages",
+    "get_space",
+    "search",
+    "get_page_history",
+    "get_labels",
+    "add_label",
+    "get_comments",
+    "add_comment",
+    "get_page_restrictions",
+]

runspec_confluence/cli.py

@@ -0,0 +1,125 @@
+"""cli.py — the ``confluence`` entry point.
+
+One binary, a verb per Confluence tool. ``rs.parse("confluence")`` resolves the
+subcommand and its args; we build a :class:`ConfluenceConfig` from the environment
+(scoped by the global ``--env``), unpack each ``.value`` at the boundary, and call
+the matching :mod:`runspec_confluence_core` helper.
+
+Failures (the core :class:`ConfluenceError` 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_confluence_core import (
+    ConfluenceConfig,
+    ConfluenceError,
+    add_comment,
+    add_label,
+    config_from_env,
+    create_page,
+    delete_page,
+    get_comments,
+    get_labels,
+    get_page,
+    get_page_ancestors,
+    get_page_children,
+    get_page_history,
+    get_page_restrictions,
+    get_space,
+    get_space_pages,
+    move_page,
+    search,
+    update_page,
+)
+
+
+def _emit(payload: Any) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _dispatch(spec: rs.RunSpec, config: ConfluenceConfig) -> Any:
+    """Run the active verb against ``config``, unpacking only its declared args."""
+    command = spec.runspec_command
+
+    # ── reads ──
+    if command == "search":
+        return search(config, spec.cql.value, start=spec.start.value, limit=spec.limit.value, expand=spec.expand.value)
+    if command == "get-page":
+        return get_page(config, page_id=spec.page_id.value, space=spec.space.value, title=spec.title.value, expand=spec.expand.value)
+    if command == "get-page-children":
+        return get_page_children(config, spec.page_id.value)
+    if command == "get-page-ancestors":
+        return get_page_ancestors(config, spec.page_id.value)
+    if command == "get-page-history":
+        return get_page_history(config, spec.page_id.value)
+    if command == "get-labels":
+        return get_labels(config, spec.page_id.value)
+    if command == "get-comments":
+        return get_comments(config, spec.page_id.value, limit=spec.limit.value)
+    if command == "get-page-restrictions":
+        return get_page_restrictions(config, spec.page_id.value)
+    if command == "get-space":
+        return get_space(config, spec.space_key.value)
+    if command == "get-space-pages":
+        return get_space_pages(config, spec.space.value, start=spec.start.value, limit=spec.limit.value)
+
+    # ── writes ──
+    if command == "create-page":
+        return create_page(
+            config,
+            spec.space.value,
+            spec.title.value,
+            spec.content.value,
+            parent_id=spec.parent_id.value,
+            representation=spec.content_format.value,
+        )
+    if command == "update-page":
+        return update_page(
+            config,
+            spec.page_id.value,
+            spec.title.value,
+            body=spec.content.value,
+            parent_id=spec.parent_id.value,
+            representation=spec.content_format.value,
+            version_comment=spec.version_comment.value,
+            minor_edit=spec.minor_edit.value,
+        )
+    if command == "delete-page":
+        return delete_page(config, spec.page_id.value, recursive=spec.recursive.value)
+    if command == "move-page":
+        return move_page(
+            config,
+            spec.space.value,
+            spec.page_id.value,
+            target_id=spec.target_id.value,
+            target_title=spec.target_title.value,
+            position=spec.position.value,
+        )
+    if command == "add-label":
+        return add_label(config, spec.page_id.value, spec.label.value)
+    if command == "add-comment":
+        return add_comment(config, spec.page_id.value, spec.text.value)
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `confluence --help`")  # pragma: no cover
+
+
+def main() -> None:
+    spec = rs.parse("confluence")
+    try:
+        config = config_from_env(env=spec.env.value)
+        result = _dispatch(spec, config)
+    except (ConfluenceError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()

runspec_confluence/runspec.toml

@@ -0,0 +1,166 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-confluence — a Confluence runnable ported from the Atlassian MCP
+# server (sooperset/mcp-atlassian), onto atlassian-python-api.
+#
+# One runnable, `confluence`, with a verb per tool. `runspec serve` re-expands
+# each verb into its own leaf MCP tool (confluence_get-page, confluence_create-page,
+# …), so a runspec-console agent calls them individually — over SSH on any fleet
+# host, with no second server process.
+#
+# Cloud and Server/Data Center. Auth is env-var driven:
+#   CONFLUENCE_URL + (CONFLUENCE_PERSONAL_TOKEN | CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN)
+# Per-environment overrides use a CONFLUENCE_<ENV>_ prefix, selected with the
+# global --env (dev/uat/prod) arg. Cloud vs Server/DC is set by CONFLUENCE_CLOUD,
+# else inferred from a .atlassian.net host.
+#
+# Reads are autonomous; writes require confirmation. Page bodies are passed in a
+# Confluence representation via --content-format (storage XHTML by default, or
+# wiki/editor). Markdown conversion is not done here.
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+[confluence]
+description = "Read and manage Confluence pages, spaces, comments, and labels (Cloud or Server/Data Center)"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "confluence get-page --page-id 12345 --expand body.storage", description = "Fetch a page with its storage body"},
+  {cmd = "confluence search --cql 'space = DOCS AND text ~ onboarding'", description = "Search content with CQL"},
+  {cmd = "confluence create-page --space DOCS --title 'Runbook' --content '<p>Steps</p>'", description = "Create a page"},
+  {cmd = "confluence add-comment --page-id 12345 --text 'Reviewed'", description = "Comment on a page"},
+]
+
+# ── global args (inherited by every verb) ──────────────────────────────────
+[confluence.args]
+env = {type = "choice", options = ["dev", "uat", "prod"], short = "-e", required = false, description = "Target environment (selects CONFLUENCE_<ENV>_* vars, falling back to CONFLUENCE_*)"}
+
+# ── reads → autonomous ─────────────────────────────────────────────────────
+
+[confluence.commands.search]
+description = "Search content with CQL (Confluence Query Language); returns one page of results"
+autonomy = "autonomous"
+[confluence.commands.search.args]
+cql = {type = "str", required = true, description = "CQL query, e.g. 'type = page AND space = DOCS AND text ~ \"onboarding\"'"}
+limit = {type = "int", default = 25, description = "Max results"}
+start = {type = "int", default = 0, description = "Pagination offset"}
+expand = {type = "str", required = false, description = "Comma-separated expand sections"}
+
+[confluence.commands.get-page]
+description = "Fetch a page by id, or by space + title"
+autonomy = "autonomous"
+[confluence.commands.get-page.args]
+page-id = {type = "str", required = false, description = "Page id"}
+space = {type = "str", required = false, description = "Space key (with --title; falls back to CONFLUENCE_SPACE)"}
+title = {type = "str", required = false, description = "Page title (with --space)"}
+expand = {type = "str", required = false, description = "Comma-separated expand sections, e.g. body.storage,version"}
+
+[confluence.commands.get-page-children]
+description = "List a page's immediate child pages"
+autonomy = "autonomous"
+[confluence.commands.get-page-children.args]
+page-id = {type = "str", required = true, description = "Parent page id"}
+
+[confluence.commands.get-page-ancestors]
+description = "List a page's ancestor pages (breadcrumb, root first)"
+autonomy = "autonomous"
+[confluence.commands.get-page-ancestors.args]
+page-id = {type = "str", required = true, description = "Page id"}
+
+[confluence.commands.get-page-history]
+description = "Return a page's content history (created/last-updated, versions)"
+autonomy = "autonomous"
+[confluence.commands.get-page-history.args]
+page-id = {type = "str", required = true, description = "Page id"}
+
+[confluence.commands.get-labels]
+description = "List a page's labels"
+autonomy = "autonomous"
+[confluence.commands.get-labels.args]
+page-id = {type = "str", required = true, description = "Page id"}
+
+[confluence.commands.get-comments]
+description = "List a page's comments (rendered bodies)"
+autonomy = "autonomous"
+[confluence.commands.get-comments.args]
+page-id = {type = "str", required = true, description = "Page id"}
+limit = {type = "int", default = 25, description = "Max comments"}
+
+[confluence.commands.get-page-restrictions]
+description = "Return the view/edit restrictions on a page"
+autonomy = "autonomous"
+[confluence.commands.get-page-restrictions.args]
+page-id = {type = "str", required = true, description = "Page id"}
+
+[confluence.commands.get-space]
+description = "Fetch a space's metadata"
+autonomy = "autonomous"
+[confluence.commands.get-space.args]
+space-key = {type = "str", required = true, description = "Space key"}
+
+[confluence.commands.get-space-pages]
+description = "List pages in a space (one page of results)"
+autonomy = "autonomous"
+[confluence.commands.get-space-pages.args]
+space = {type = "str", required = true, description = "Space key"}
+limit = {type = "int", default = 50, description = "Max results"}
+start = {type = "int", default = 0, description = "Pagination offset"}
+
+# ── writes → confirm ───────────────────────────────────────────────────────
+
+[confluence.commands.create-page]
+description = "Create a page. --content is in the --content-format representation."
+autonomy = "confirm"
+[confluence.commands.create-page.args]
+space = {type = "str", required = true, description = "Space key"}
+title = {type = "str", required = true, description = "Page title"}
+content = {type = "str", required = true, description = "Page body in the --content-format representation"}
+parent-id = {type = "str", required = false, description = "Parent page id"}
+content-format = {type = "choice", options = ["storage", "wiki", "editor"], default = "storage", description = "Body representation (storage = Confluence XHTML)"}
+
+[confluence.commands.update-page]
+description = "Update a page. --title is required by the API even when only the body changes."
+autonomy = "confirm"
+[confluence.commands.update-page.args]
+page-id = {type = "str", required = true, description = "Page id"}
+title = {type = "str", required = true, description = "Page title (pass the current title if unchanged)"}
+content = {type = "str", required = false, description = "New body in the --content-format representation"}
+parent-id = {type = "str", required = false, description = "New parent page id"}
+content-format = {type = "choice", options = ["storage", "wiki", "editor"], default = "storage", description = "Body representation"}
+version-comment = {type = "str", required = false, description = "Version comment for the edit"}
+minor-edit = {type = "flag", default = false, description = "Mark as a minor edit (no notifications)"}
+
+[confluence.commands.delete-page]
+description = "Delete a page (and, with --recursive, its descendants)"
+autonomy = "confirm"
+[confluence.commands.delete-page.args]
+page-id = {type = "str", required = true, description = "Page id"}
+recursive = {type = "flag", default = false, description = "Also delete descendant pages"}
+
+[confluence.commands.move-page]
+description = "Move a page relative to a target (append under it, or above/below)"
+autonomy = "confirm"
+[confluence.commands.move-page.args]
+space = {type = "str", required = true, description = "Space key of the page"}
+page-id = {type = "str", required = true, description = "Page id to move"}
+target-id = {type = "str", required = false, description = "Target page id"}
+target-title = {type = "str", required = false, description = "Target page title (alternative to --target-id)"}
+position = {type = "choice", options = ["append", "above", "below"], default = "append", description = "Placement relative to the target"}
+
+[confluence.commands.add-label]
+description = "Add a label to a page"
+autonomy = "confirm"
+[confluence.commands.add-label.args]
+page-id = {type = "str", required = true, description = "Page id"}
+label = {type = "str", required = true, description = "Label to add"}
+
+[confluence.commands.add-comment]
+description = "Add a comment to a page"
+autonomy = "confirm"
+[confluence.commands.add-comment.args]
+page-id = {type = "str", required = true, description = "Page id"}
+text = {type = "str", required = true, description = "Comment text"}

runspec_confluence-0.1.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-confluence
+Version: 0.1.0
+Summary: Confluence runnable for runspec — pages, search, comments, labels, and restrictions (Cloud + Server/Data Center)
+Requires-Python: >=3.10
+Requires-Dist: runspec-confluence-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_confluence-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+runspec_confluence/__init__.py,sha256=3ojWN41pnkHUURxWlGHDeP6J_mVPXUQZ1NfqpgwcthI,1234
+runspec_confluence/cli.py,sha256=UmdQibFSVv2wX-BHTKWS8tvYUcNmNVy58Iab57shcKM,4235
+runspec_confluence/runspec.toml,sha256=EArKbgtvENH2l-OhQJtum7P3oBnkOmhmunU14PeNdQo,8707
+runspec_confluence-0.1.0.dist-info/METADATA,sha256=ddwZA_JBrmwUSIKYeAt626YsZ0-Fb_h6ruAkloQI4YQ,431
+runspec_confluence-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+runspec_confluence-0.1.0.dist-info/entry_points.txt,sha256=ilX_-nfCAEqUtobdmyrHn7FD81yvrRkT1dr7NqviM_8,59
+runspec_confluence-0.1.0.dist-info/RECORD,,

runspec_confluence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

runspec_confluence-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+confluence = runspec_confluence.cli:main