runspec-confluence-core 0.1.0__tar.gz

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

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `runspec-confluence-core` are documented here.
+
+## [0.1.0] — 2026-08-07
+
+Initial release. Pure-Python Confluence helpers over `atlassian-python-api` — the
+importable core behind `runspec-confluence`. No `runspec` dependency, no
+`runspec.toml`, no entry points (surfaces zero runnables).
+
+- `ConfluenceConfig` + `config_from_env(env=None)` — env-var auth
+  (`CONFLUENCE_URL`, `CONFLUENCE_USERNAME`/`CONFLUENCE_API_TOKEN` for Cloud/DC
+  basic, `CONFLUENCE_PERSONAL_TOKEN` for DC PAT) with `CONFLUENCE_<ENV>_*`
+  prefixes selected by `--env`. Cloud vs Server/DC via `CONFLUENCE_CLOUD` or a
+  `.atlassian.net` host.
+- `build_client` constructs `atlassian.Confluence`, picking exactly one auth mode.
+- Operation helpers: pages (get/children/ancestors/create/update/delete/move,
+  space listing + space metadata), CQL `search`, and page content
+  (history/labels/comments/restrictions).
+- `translate_errors` surfaces the SDK's `requests` exceptions as `ConfluenceError`.
+
+Content is passed in a Confluence `representation` (`storage` XHTML default, or
+`wiki`/`editor`). Deferred: markdown↔storage conversion, attachments/images,
+page diffs, space page-tree, setting restrictions, inline comments, templates,
+analytics, OAuth 2.0.

runspec_confluence_core-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: runspec-confluence-core
+Version: 0.1.0
+Summary: Pure-Python Confluence helpers (over atlassian-python-api) — the importable core behind runspec-confluence (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_confluence_core-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-confluence-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python Confluence helpers (over atlassian-python-api) — the importable core behind runspec-confluence (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_confluence_core-0.1.0/runspec_confluence_core/__init__.py

@@ -0,0 +1,67 @@
+"""runspec-confluence-core — Confluence 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-confluence``
+depends on it and wraps each helper as a verb of the ``confluence`` runnable.
+
+Every operation takes an explicit :class:`ConfluenceConfig` first argument, so a
+private (e.g. Nexus-hosted) wrapper package can inject credentials in code, bake in
+a default ``space`` / ``env``, and build on top. Each function returns plain data
+and raises :class:`ConfluenceError` on failure. Cloud and Server/Data Center are
+both supported.
+"""
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import VALID_ENVS, ConfluenceConfig, config_from_env
+from runspec_confluence_core.content import (
+    add_comment,
+    add_label,
+    get_comments,
+    get_labels,
+    get_page_history,
+    get_page_restrictions,
+)
+from runspec_confluence_core.errors import ConfluenceError
+from runspec_confluence_core.pages import (
+    create_page,
+    delete_page,
+    get_page,
+    get_page_ancestors,
+    get_page_children,
+    get_space,
+    get_space_pages,
+    move_page,
+    update_page,
+)
+from runspec_confluence_core.search import search
+
+__all__ = [
+    # config / client
+    "ConfluenceConfig",
+    "ConfluenceError",
+    "config_from_env",
+    "build_client",
+    "translate_errors",
+    "VALID_ENVS",
+    # pages
+    "get_page",
+    "get_page_children",
+    "get_page_ancestors",
+    "create_page",
+    "update_page",
+    "delete_page",
+    "move_page",
+    "get_space_pages",
+    "get_space",
+    # search
+    "search",
+    # content
+    "get_page_history",
+    "get_labels",
+    "add_label",
+    "get_comments",
+    "add_comment",
+    "get_page_restrictions",
+]

runspec_confluence_core-0.1.0/runspec_confluence_core/client.py

@@ -0,0 +1,68 @@
+"""client.py — build an ``atlassian.Confluence`` client + shared op helpers.
+
+``build_client`` picks exactly one auth mode (Basic when username+api_token are
+set, else Bearer PAT). ``@translate_errors`` wraps each operation so the SDK's
+``requests`` exceptions surface as a :class:`ConfluenceError` carrying
+Confluence's own error message.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import requests
+from atlassian import Confluence
+
+from runspec_confluence_core.config import ConfluenceConfig
+from runspec_confluence_core.errors import ConfluenceError
+
+_T = TypeVar("_T")
+
+
+def _auth_kwargs(config: ConfluenceConfig) -> 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 ConfluenceError("ConfluenceConfig has no usable credentials (need personal_token or username+api_token)")
+    return base
+
+
+def build_client(config: ConfluenceConfig) -> Confluence:
+    """Construct an ``atlassian.Confluence`` client for ``config``."""
+    return Confluence(**_auth_kwargs(config))
+
+
+def _message(exc: requests.HTTPError) -> str:
+    """Extract a human-readable message from a Confluence error response."""
+    resp = getattr(exc, "response", None)
+    if resp is None:
+        return f"Confluence request failed: {exc}"
+    try:
+        body = resp.json()
+    except Exception:
+        return f"Confluence {resp.status_code}: {resp.text[:500]}"
+    if isinstance(body, dict):
+        message = body.get("message") or body.get("reason")
+        if message:
+            return f"Confluence {resp.status_code}: {message}"
+    return f"Confluence {resp.status_code}: {str(body)[:500]}"
+
+
+def translate_errors(fn: Callable[..., _T]) -> Callable[..., _T]:
+    """Decorator: turn the SDK's ``requests`` exceptions into ``ConfluenceError``."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> _T:
+        try:
+            return fn(*args, **kwargs)
+        except requests.HTTPError as exc:
+            raise ConfluenceError(_message(exc)) from exc
+        except requests.RequestException as exc:
+            raise ConfluenceError(f"Confluence request failed: {exc}") from exc
+
+    return wrapper

runspec_confluence_core-0.1.0/runspec_confluence_core/config.py

@@ -0,0 +1,108 @@
+"""config.py — connection + identity for a Confluence instance, from the environment.
+
+Mirrors ``runspec-jira-core``'s config: ``config_from_env`` reads the
+``CONFLUENCE_*`` family (with an optional ``CONFLUENCE_<ENV>_*`` prefix selected by
+``--env``). Every operation function takes an explicit ``ConfluenceConfig`` first
+argument, so a private (e.g. Nexus-hosted) wrapper can inject credentials in code
+and bake in a default ``space`` / ``env``.
+
+Cloud vs Server/Data Center is resolved once: an explicit ``CONFLUENCE_CLOUD`` wins,
+otherwise a ``.atlassian.net`` host is treated as Cloud and anything else as
+Server/DC.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from runspec_confluence_core.errors import ConfluenceError
+
+VALID_ENVS = ("dev", "uat", "prod")
+
+_FALSEY = ("0", "false", "no", "off")
+_TRUTHY = ("1", "true", "yes", "on")
+
+
+@dataclass
+class ConfluenceConfig:
+    """Connection + identity for a Confluence 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). ``space`` is an optional
+    default a wrapper can bake in.
+    """
+
+    url: str
+    cloud: bool
+    username: str | None = None
+    api_token: str | None = None
+    personal_token: str | None = None
+    space: 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) -> ConfluenceConfig:
+    """Build a :class:`ConfluenceConfig` from environment variables.
+
+    When ``env`` (or the ``CONFLUENCE_ENV`` variable) selects dev/uat/prod, the
+    environment-prefixed variables are read first (e.g. ``CONFLUENCE_UAT_URL``),
+    falling back to the unprefixed ``CONFLUENCE_*`` family. Raises
+    :class:`ConfluenceError` when the env label is invalid, the base URL is
+    missing, or no usable credentials are configured.
+    """
+    env = env or os.environ.get("CONFLUENCE_ENV")
+    if env is not None:
+        env = env.lower()
+        if env not in VALID_ENVS:
+            raise ConfluenceError(f"Invalid env {env!r} — expected one of {', '.join(VALID_ENVS)}")
+
+    def lookup(suffix: str) -> str | None:
+        names = []
+        if env:
+            names.append(f"CONFLUENCE_{env.upper()}_{suffix}")
+        names.append(f"CONFLUENCE_{suffix}")
+        return _env_first(names)
+
+    url = lookup("URL")
+    if not url:
+        hint = f"CONFLUENCE_{env.upper()}_URL" if env else "CONFLUENCE_URL"
+        raise ConfluenceError(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 ConfluenceError("No credentials configured — set CONFLUENCE_PERSONAL_TOKEN (Server/DC PAT) or CONFLUENCE_USERNAME + CONFLUENCE_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 ConfluenceConfig(
+        url=url.rstrip("/"),
+        cloud=_resolve_cloud(url, lookup("CLOUD")),
+        username=username,
+        api_token=api_token,
+        personal_token=personal_token,
+        space=lookup("SPACE"),
+        verify_ssl=verify_ssl,
+        env=env,
+    )

runspec_confluence_core-0.1.0/runspec_confluence_core/content.py

@@ -0,0 +1,44 @@
+"""content.py — history, labels, comments, and restrictions for a page."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import ConfluenceConfig
+
+
+@translate_errors
+def get_page_history(config: ConfluenceConfig, page_id: str) -> Any:
+    """Return a page's content history (created/last-updated, versions)."""
+    return build_client(config).get_content_history(page_id)
+
+
+@translate_errors
+def get_labels(config: ConfluenceConfig, page_id: str) -> Any:
+    """List a page's labels."""
+    return build_client(config).get_page_labels(page_id)
+
+
+@translate_errors
+def add_label(config: ConfluenceConfig, page_id: str, label: str) -> Any:
+    """Add a label to a page."""
+    return build_client(config).set_page_label(page_id, label)
+
+
+@translate_errors
+def get_comments(config: ConfluenceConfig, page_id: str, *, limit: int = 25) -> Any:
+    """List a page's comments (rendered bodies)."""
+    return build_client(config).get_page_comments(page_id, expand="body.view", limit=limit)
+
+
+@translate_errors
+def add_comment(config: ConfluenceConfig, page_id: str, text: str) -> Any:
+    """Add a comment to a page."""
+    return build_client(config).add_comment(page_id, text)
+
+
+@translate_errors
+def get_page_restrictions(config: ConfluenceConfig, page_id: str) -> Any:
+    """Return the view/edit restrictions on a page."""
+    return build_client(config).get_all_restrictions_for_content(page_id)

runspec_confluence_core-0.1.0/runspec_confluence_core/errors.py

@@ -0,0 +1,13 @@
+"""errors.py — the exception type raised across runspec-confluence-core.
+
+Every operation function raises :class:`ConfluenceError` on configuration
+problems, invalid arguments, and non-2xx API responses (the underlying
+``atlassian-python-api`` raises ``requests`` exceptions, translated to
+``ConfluenceError`` at the operation boundary).
+"""
+
+from __future__ import annotations
+
+
+class ConfluenceError(Exception):
+    """Raised on config problems, invalid arguments, and Confluence API errors."""

runspec_confluence_core-0.1.0/runspec_confluence_core/pages.py

@@ -0,0 +1,114 @@
+"""pages.py — page read/create/update/delete/move + space listing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import ConfluenceConfig
+from runspec_confluence_core.errors import ConfluenceError
+
+
+@translate_errors
+def get_page(
+    config: ConfluenceConfig,
+    *,
+    page_id: str | None = None,
+    space: str | None = None,
+    title: str | None = None,
+    expand: str | None = None,
+) -> Any:
+    """Fetch a page by id, or by space + title. ``expand`` (e.g.
+    ``body.storage,version``) controls what is returned."""
+    client = build_client(config)
+    if page_id:
+        return client.get_page_by_id(page_id, expand=expand)
+    space = space or config.space
+    if space and title:
+        return client.get_page_by_title(space, title, expand=expand)
+    raise ConfluenceError("get-page needs --page-id, or --space (or CONFLUENCE_SPACE) and --title")
+
+
+@translate_errors
+def get_page_children(config: ConfluenceConfig, page_id: str) -> Any:
+    """List a page's immediate child pages."""
+    return build_client(config).get_child_pages(page_id)
+
+
+@translate_errors
+def get_page_ancestors(config: ConfluenceConfig, page_id: str) -> Any:
+    """List a page's ancestor pages (its breadcrumb, root first)."""
+    return build_client(config).get_page_ancestors(page_id)
+
+
+@translate_errors
+def create_page(
+    config: ConfluenceConfig,
+    space: str,
+    title: str,
+    body: str,
+    *,
+    parent_id: str | None = None,
+    representation: str = "storage",
+) -> Any:
+    """Create a page. ``body`` is in ``representation`` format (``storage`` XHTML by
+    default, or ``wiki`` / ``editor``)."""
+    return build_client(config).create_page(space, title, body, parent_id=parent_id, representation=representation)
+
+
+@translate_errors
+def update_page(
+    config: ConfluenceConfig,
+    page_id: str,
+    title: str,
+    *,
+    body: str | None = None,
+    parent_id: str | None = None,
+    representation: str = "storage",
+    version_comment: str | None = None,
+    minor_edit: bool = False,
+) -> Any:
+    """Update a page. ``title`` is required by the API even when only the body
+    changes (pass the page's current title)."""
+    return build_client(config).update_page(
+        page_id,
+        title,
+        body=body,
+        parent_id=parent_id,
+        representation=representation,
+        minor_edit=minor_edit,
+        version_comment=version_comment,
+    )
+
+
+@translate_errors
+def delete_page(config: ConfluenceConfig, page_id: str, *, recursive: bool = False) -> dict[str, Any]:
+    """Delete a page (and, with ``recursive``, its descendants)."""
+    build_client(config).remove_page(page_id, recursive=recursive)
+    return {"page_id": page_id, "deleted": True}
+
+
+@translate_errors
+def move_page(
+    config: ConfluenceConfig,
+    space: str,
+    page_id: str,
+    *,
+    target_id: str | None = None,
+    target_title: str | None = None,
+    position: str = "append",
+) -> Any:
+    """Move a page relative to a target (``append`` under it, or ``above``/``below``)."""
+    return build_client(config).move_page(space, page_id, target_id=target_id, target_title=target_title, position=position)
+
+
+@translate_errors
+def get_space_pages(config: ConfluenceConfig, space: str, *, start: int = 0, limit: int = 50) -> Any:
+    """List pages in a space (one page of results)."""
+    return build_client(config).get_all_pages_from_space(space, start=start, limit=limit)
+
+
+@translate_errors
+def get_space(config: ConfluenceConfig, space_key: str) -> Any:
+    """Fetch a space's metadata."""
+    return build_client(config).get_space(space_key)

runspec_confluence_core-0.1.0/runspec_confluence_core/search.py

@@ -0,0 +1,15 @@
+"""search.py — CQL content search."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import ConfluenceConfig
+
+
+@translate_errors
+def search(config: ConfluenceConfig, cql: str, *, start: int = 0, limit: int = 25, expand: str | None = None) -> Any:
+    """Search content with CQL (Confluence Query Language), e.g.
+    ``type = page AND space = DOCS AND text ~ "onboarding"``. Returns one page."""
+    return build_client(config).cql(cql, start=start, limit=limit, expand=expand)

runspec_confluence_core-0.1.0/tests/conftest.py

@@ -0,0 +1,72 @@
+"""Shared test helpers: a clean CONFLUENCE_* env and a fake Confluence installer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from runspec_confluence_core import client as client_mod
+
+_SUFFIXES = ("URL", "USERNAME", "API_TOKEN", "PERSONAL_TOKEN", "CLOUD", "SPACE", "VERIFY_SSL")
+_ALL_VARS = ["CONFLUENCE_ENV"] + [f"CONFLUENCE_{s}" for s in _SUFFIXES]
+for _env in ("DEV", "UAT", "PROD"):
+    _ALL_VARS += [f"CONFLUENCE_{_env}_{s}" for s in _SUFFIXES]
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    for var in _ALL_VARS:
+        monkeypatch.delenv(var, raising=False)
+
+
+class FakeClient:
+    """Records method calls; returns preset values (or raises preset exceptions)."""
+
+    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))
+            value = self._returns.get(name)
+            if isinstance(value, BaseException):
+                raise value
+            return value() if callable(value) else value
+
+        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} was not called; calls={[c[0] for c in self.calls]}")
+
+
+class FakeResp:
+    def __init__(self, status: int, payload: Any):
+        self.status_code = status
+        self._payload = payload
+        self.text = str(payload)
+
+    def json(self) -> Any:
+        return self._payload
+
+
+@pytest.fixture
+def install(monkeypatch):
+    """Install a fake Confluence client; return (client, made_kwargs)."""
+
+    def _install(returns: dict[str, Any] | None = None):
+        client = FakeClient(returns)
+        made: dict[str, dict] = {}
+
+        def make(**kw):
+            made["kw"] = kw
+            return client
+
+        monkeypatch.setattr(client_mod, "Confluence", make)
+        return client, made
+
+    return _install

runspec_confluence_core-0.1.0/tests/test_config.py

@@ -0,0 +1,75 @@
+import pytest
+
+from runspec_confluence_core.config import ConfluenceConfig, config_from_env
+
+
+def test_cloud_basic_from_env(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_URL", "https://acme.atlassian.net/wiki")
+    monkeypatch.setenv("CONFLUENCE_USERNAME", "me@acme.com")
+    monkeypatch.setenv("CONFLUENCE_API_TOKEN", "tok")
+    cfg = config_from_env()
+    assert cfg.cloud is True
+    assert cfg.username == "me@acme.com"
+    assert cfg.api_token == "tok"
+
+
+def test_dc_pat_not_cloud_and_strips_slash(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_URL", "https://wiki.corp.example/")
+    monkeypatch.setenv("CONFLUENCE_PERSONAL_TOKEN", "pat")
+    cfg = config_from_env()
+    assert cfg.url == "https://wiki.corp.example"
+    assert cfg.cloud is False
+    assert cfg.personal_token == "pat"
+
+
+def test_cloud_override(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_URL", "https://wiki.corp.example")
+    monkeypatch.setenv("CONFLUENCE_PERSONAL_TOKEN", "pat")
+    monkeypatch.setenv("CONFLUENCE_CLOUD", "yes")
+    assert config_from_env().cloud is True
+
+
+def test_env_prefixed_resolution(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_UAT_URL", "https://uat.atlassian.net/wiki")
+    monkeypatch.setenv("CONFLUENCE_UAT_PERSONAL_TOKEN", "uat")
+    cfg = config_from_env(env="uat")
+    assert cfg.personal_token == "uat"
+    assert cfg.env == "uat"
+
+
+def test_env_prefixed_falls_back(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_PROD_URL", "https://prod.atlassian.net/wiki")
+    monkeypatch.setenv("CONFLUENCE_USERNAME", "u@x")
+    monkeypatch.setenv("CONFLUENCE_API_TOKEN", "shared")
+    cfg = config_from_env(env="prod")
+    assert cfg.api_token == "shared"
+
+
+def test_invalid_env(monkeypatch):
+    with pytest.raises(Exception, match="Invalid env"):
+        config_from_env(env="staging")
+
+
+def test_missing_url(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_PERSONAL_TOKEN", "p")
+    with pytest.raises(Exception, match="No base URL"):
+        config_from_env()
+
+
+def test_missing_credentials(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_URL", "https://acme.atlassian.net/wiki")
+    with pytest.raises(Exception, match="No credentials"):
+        config_from_env()
+
+
+def test_space_default(monkeypatch):
+    monkeypatch.setenv("CONFLUENCE_URL", "https://acme.atlassian.net/wiki")
+    monkeypatch.setenv("CONFLUENCE_PERSONAL_TOKEN", "p")
+    monkeypatch.setenv("CONFLUENCE_SPACE", "DOCS")
+    assert config_from_env().space == "DOCS"
+
+
+def test_dataclass_defaults():
+    cfg = ConfluenceConfig(url="https://x", cloud=True)
+    assert cfg.verify_ssl is True
+    assert cfg.space is None

runspec_confluence_core-0.1.0/tests/test_ops.py

@@ -0,0 +1,125 @@
+"""Operation wiring: each core op calls the right SDK method, resolves
+space defaults, branches get-page by id vs title, and translates errors."""
+
+import pytest
+import requests
+
+from runspec_confluence_core import (
+    ConfluenceConfig,
+    ConfluenceError,
+    add_comment,
+    add_label,
+    build_client,
+    create_page,
+    delete_page,
+    get_comments,
+    get_page,
+    search,
+    update_page,
+)
+from tests.conftest import FakeResp
+
+CLOUD = ConfluenceConfig(url="https://acme.atlassian.net/wiki", cloud=True, username="me@x.com", api_token="tok")
+DC = ConfluenceConfig(url="https://wiki.corp", cloud=False, personal_token="pat")
+
+
+def test_build_client_basic_kwargs(install):
+    _, made = install()
+    build_client(CLOUD)
+    assert made["kw"] == {"url": "https://acme.atlassian.net/wiki", "cloud": True, "verify_ssl": True, "username": "me@x.com", "password": "tok"}
+
+
+def test_build_client_pat_kwargs(install):
+    _, made = install()
+    build_client(DC)
+    assert made["kw"] == {"url": "https://wiki.corp", "cloud": False, "verify_ssl": True, "token": "pat"}
+
+
+def test_get_page_by_id(install):
+    client, _ = install(returns={"get_page_by_id": {"id": "1"}})
+    assert get_page(CLOUD, page_id="1", expand="body.storage") == {"id": "1"}
+    args, kwargs = client.last("get_page_by_id")
+    assert args == ("1",)
+    assert kwargs["expand"] == "body.storage"
+
+
+def test_get_page_by_title(install):
+    client, _ = install(returns={"get_page_by_title": {"id": "2"}})
+    get_page(CLOUD, space="DOCS", title="Home")
+    args, _ = client.last("get_page_by_title")
+    assert args == ("DOCS", "Home")
+
+
+def test_get_page_uses_config_space(install):
+    cfg = ConfluenceConfig(url="https://acme.atlassian.net/wiki", cloud=True, personal_token="p", space="TEAM")
+    client, _ = install(returns={"get_page_by_title": {}})
+    get_page(cfg, title="Runbook")
+    args, _ = client.last("get_page_by_title")
+    assert args == ("TEAM", "Runbook")
+
+
+def test_get_page_without_locator_raises(install):
+    install()
+    with pytest.raises(ConfluenceError, match="page-id"):
+        get_page(CLOUD)
+
+
+def test_create_page_passes_representation(install):
+    client, _ = install(returns={"create_page": {"id": "9"}})
+    create_page(CLOUD, "DOCS", "New", "<p>hi</p>", parent_id="3", representation="storage")
+    args, kwargs = client.last("create_page")
+    assert args == ("DOCS", "New", "<p>hi</p>")
+    assert kwargs == {"parent_id": "3", "representation": "storage"}
+
+
+def test_update_page_threads_args(install):
+    client, _ = install(returns={"update_page": {}})
+    update_page(CLOUD, "9", "Title", body="<p>x</p>", version_comment="tweak", minor_edit=True)
+    args, kwargs = client.last("update_page")
+    assert args == ("9", "Title")
+    assert kwargs["version_comment"] == "tweak"
+    assert kwargs["minor_edit"] is True
+
+
+def test_delete_page_returns_status(install):
+    client, _ = install()
+    assert delete_page(CLOUD, "9", recursive=True) == {"page_id": "9", "deleted": True}
+    _, kwargs = client.last("remove_page")
+    assert kwargs["recursive"] is True
+
+
+def test_search_calls_cql(install):
+    client, _ = install(returns={"cql": {"results": []}})
+    search(CLOUD, "type = page", limit=5)
+    args, kwargs = client.last("cql")
+    assert args == ("type = page",)
+    assert kwargs["limit"] == 5
+
+
+def test_get_comments_expands_body(install):
+    client, _ = install(returns={"get_page_comments": {"results": []}})
+    get_comments(CLOUD, "9")
+    _, kwargs = client.last("get_page_comments")
+    assert kwargs["expand"] == "body.view"
+
+
+def test_add_label(install):
+    client, _ = install()
+    add_label(CLOUD, "9", "runbook")
+    args, _ = client.last("set_page_label")
+    assert args == ("9", "runbook")
+
+
+def test_add_comment(install):
+    client, _ = install()
+    add_comment(CLOUD, "9", "looks good")
+    args, _ = client.last("add_comment")
+    assert args == ("9", "looks good")
+
+
+def test_http_error_becomes_confluence_error(install):
+    err = requests.HTTPError("boom")
+    err.response = FakeResp(404, {"message": "No content found with id: 9"})
+    install(returns={"get_page_by_id": err})
+    with pytest.raises(ConfluenceError, match="No content found"):
+        get_page(CLOUD, page_id="9")