docspan 0.1.0__py3-none-any.whl

docspan/backends/confluence/backend.py

@@ -0,0 +1,227 @@
+"""Confluence backend."""
+
+from __future__ import annotations
+
+import logging
+import os
+import pathlib
+import re
+from typing import TYPE_CHECKING, Optional
+
+import markdownify as md_lib
+
+from docspan.backends.base import Backend, PullResult, PushResult
+from docspan.backends.confluence.adf.converter import AdfConverter
+from docspan.backends.confluence.config.models import ConfluenceConfig as InternalConfluenceConfig
+from docspan.backends.confluence.markdown.parser import MarkdownParser
+from docspan.backends.confluence.models.page import ConfluencePage
+from docspan.backends.confluence.services.confluence.client import ConfluenceClient
+from docspan.backends.confluence.services.confluence.comment_client import ConfluenceCommentClient
+from docspan.config import ConfluenceConfig
+from docspan.core.paths import COMMENTS_SUFFIX
+
+if TYPE_CHECKING:
+    from docspan.config import MarkgateConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ConfluenceBackend(Backend):
+    name = "confluence"
+
+    def __init__(self, config: ConfluenceConfig) -> None:
+        self.config = config
+        self._client: Optional[ConfluenceClient] = None
+        self._comment_client: Optional[ConfluenceCommentClient] = None
+        self._internal_cfg: Optional[InternalConfluenceConfig] = None
+
+    @classmethod
+    def from_config(cls, markgate_config: "MarkgateConfig") -> "ConfluenceBackend":
+        return cls(markgate_config.backends.confluence or ConfluenceConfig())
+
+    def _ensure_client(self) -> None:
+        if self._client is not None:
+            return
+        base_url = self.config.base_url or os.getenv("CONFLUENCE_BASE_URL")
+        username = self.config.username or os.getenv("ATLASSIAN_USER_NAME")
+        api_token = self.config.api_token or os.getenv("CONFLUENCE_API_TOKEN")
+        if not all([base_url, username, api_token]):
+            raise RuntimeError(
+                "Confluence credentials incomplete. Run: docspan auth setup confluence\n"
+                "Or set CONFLUENCE_BASE_URL, ATLASSIAN_USER_NAME, CONFLUENCE_API_TOKEN."
+            )
+        self._internal_cfg = InternalConfluenceConfig(
+            base_url=base_url,
+            username=username,
+            api_token=api_token,
+        )
+        self._client = ConfluenceClient(self._internal_cfg)
+
+    def _ensure_comment_client(self) -> None:
+        if self._comment_client is not None:
+            return
+        self._ensure_client()
+        assert self._internal_cfg is not None
+        self._comment_client = ConfluenceCommentClient(self._internal_cfg)
+
+    # ── Comment sidecar ────────────────────────────────────────────────────
+
+    @staticmethod
+    def _format_comment(comment: dict) -> list[str]:
+        comment_id = comment.get("id", "unknown")
+        author = (
+            comment.get("createdBy", {}).get("displayName")
+            or comment.get("version", {}).get("by", {}).get("displayName", "Unknown")
+        )
+        date = (
+            comment.get("version", {}).get("createdAt", "")
+            or comment.get("version", {}).get("friendlyWhen", "")
+        )
+        lines: list[str] = [f"### [{comment_id}] {author} — {date}", ""]
+        selection = (
+            comment.get("properties", {}).get("inlineOriginalSelection", "")
+            or comment.get("inlineCommentProperties", {}).get("textSelection", "")
+        )
+        if selection:
+            lines += [f'> Selection: "{selection}"', ""]
+        body_html = (
+            comment.get("body", {}).get("storage", {}).get("value", "")
+            or comment.get("body", {}).get("view", {}).get("value", "")
+        )
+        body_text = re.sub(r"<[^<]+?>", "", body_html).strip()
+        if body_text:
+            lines.append(body_text)
+        lines += ["", "---", ""]
+        return lines
+
+    def _write_comment_sidecar(
+        self,
+        local_path: str,
+        page_title: str,
+        inline_comments: list,
+        footer_comments: list,
+    ) -> None:
+        lines = [f"# Comments: {page_title}", ""]
+        if inline_comments:
+            lines += ["## Inline comments", ""]
+            for comment in inline_comments:
+                lines += self._format_comment(comment)
+        if footer_comments:
+            lines += ["## Footer comments", ""]
+            for comment in footer_comments:
+                lines += self._format_comment(comment)
+        sidecar_path = str(local_path) + COMMENTS_SUFFIX
+        pathlib.Path(sidecar_path).write_text("\n".join(lines))
+
+    # ── Backend interface ──────────────────────────────────────────────────
+
+    def push(self, local_path: str, doc_id: str, **kwargs: object) -> PushResult:
+        """Convert local markdown to ADF and update the Confluence page."""
+        self._ensure_client()
+        assert self._client is not None
+        try:
+            content = pathlib.Path(local_path).read_text()
+            ast = MarkdownParser().parse(content)
+            adf_doc = AdfConverter().convert(ast)
+
+            page = self._client.get_page(doc_id)
+            title = page.get("title", "Untitled")
+            version = page.get("version", {}).get("number", 1)
+            parent_id = page.get("parentId") or (page.get("ancestors") or [{}])[-1].get("id", "")
+
+            confluence_page = ConfluencePage(
+                id=doc_id,
+                title=title,
+                content=adf_doc,
+                parent_id=parent_id,
+                version=version,
+            )
+            self._client.update_page(confluence_page)
+            base_url = self.config.base_url or ""
+            return PushResult(status="ok", doc_id=doc_id, url=f"{base_url}/pages/{doc_id}")
+        except Exception as exc:
+            return PushResult(status="error", doc_id=doc_id, message=str(exc))
+
+    def pull(self, doc_id: str, local_path: str, **kwargs: object) -> PullResult:
+        """Fetch Confluence page storage content and convert to markdown."""
+        self._ensure_client()
+        assert self._client is not None
+        try:
+            page = self._client.get_page(doc_id)
+            storage_html = page.get("body", {}).get("storage", {}).get("value", "")
+            markdown = md_lib.markdownify(storage_html, heading_style="ATX", strip=["script", "style"])
+            pathlib.Path(local_path).parent.mkdir(parents=True, exist_ok=True)
+            pathlib.Path(local_path).write_text(markdown)
+
+            page_title = page.get("title", "Untitled")
+            try:
+                self._ensure_comment_client()
+            except Exception:
+                logger.warning("Could not initialise comment client for %s; skipping comments", doc_id, exc_info=True)
+
+            inline_comments: list = []
+            footer_comments: list = []
+
+            try:
+                inline_comments = self._comment_client.get_page_inline_comments(doc_id)  # type: ignore[union-attr]
+            except Exception as exc:
+                try:
+                    v1_result = self._comment_client.get_comments(doc_id)  # type: ignore[union-attr]
+                    inline_comments = v1_result.get("results", [])
+                except Exception as fallback_exc:
+                    logger.warning(
+                        "Could not fetch inline comments for %s (v2: %s, v1 fallback: %s)",
+                        doc_id, exc, fallback_exc,
+                    )
+
+            try:
+                footer_comments = self._comment_client.get_page_footer_comments(doc_id)  # type: ignore[union-attr]
+            except Exception as exc:
+                logger.warning("Could not fetch footer comments for %s: %s", doc_id, exc)
+
+            if inline_comments or footer_comments:
+                self._write_comment_sidecar(local_path, page_title, inline_comments, footer_comments)
+
+            return PullResult(status="ok", doc_id=doc_id, local_path=local_path)
+        except Exception as exc:
+            return PullResult(status="error", doc_id=doc_id, local_path=local_path, message=str(exc))
+
+    def get_remote_version(self, doc_id: str) -> str:
+        """Return the current Confluence page version number as a string."""
+        self._ensure_client()
+        assert self._client is not None
+        page = self._client.get_page(doc_id)
+        return str(page["version"]["number"])
+
+    def auth_setup(self) -> None:
+        """Interactive Confluence auth setup — prompts for credentials and prints YAML snippet."""
+        print("\nConfluence auth setup")
+        print("=" * 40)
+        base_url = input("Confluence base URL (e.g. https://yourorg.atlassian.net): ").strip()
+        username = input("Atlassian username (email): ").strip()
+        print(
+            f"\nAdd to markgate.yaml:\n\n"
+            f"backends:\n"
+            f"  confluence:\n"
+            f"    base_url: {base_url}\n"
+            f"    username: {username}\n"
+            f"    api_token: <your-token>  # from id.atlassian.com/manage-profile/security/api-tokens\n"
+        )
+        print("Done. Test with: docspan status")
+
+    def validate_config(self) -> None:
+        base_url = self.config.base_url or os.getenv("CONFLUENCE_BASE_URL")
+        username = self.config.username or os.getenv("ATLASSIAN_USER_NAME")
+        api_token = self.config.api_token or os.getenv("CONFLUENCE_API_TOKEN")
+        missing = []
+        if not base_url:
+            missing.append("base_url / CONFLUENCE_BASE_URL")
+        if not username:
+            missing.append("username / ATLASSIAN_USER_NAME")
+        if not api_token:
+            missing.append("api_token / CONFLUENCE_API_TOKEN")
+        if missing:
+            raise ValueError(
+                f"Missing Confluence config: {', '.join(missing)}. "
+                "Run: docspan auth setup confluence"
+            )

docspan/backends/confluence/client.py

@@ -0,0 +1,44 @@
+"""Confluence REST API client — stub, to be ported from markdown-confluence."""
+
+import requests
+from requests.auth import HTTPBasicAuth
+
+
+class ConfluenceClient:
+    def __init__(self, base_url: str, username: str, api_token: str):
+        self.base_url = base_url.rstrip("/")
+        self.auth = HTTPBasicAuth(username, api_token)
+        self.session = requests.Session()
+        self.session.auth = self.auth
+        self.session.headers.update({"Content-Type": "application/json"})
+
+    def get_page(self, page_id: str) -> dict:
+        url = f"{self.base_url}/wiki/rest/api/content/{page_id}?expand=body.storage,version"
+        resp = self.session.get(url)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_page_as_markdown(self, page_id: str) -> str:
+        """Fetch page storage format and convert to markdown."""
+        page = self.get_page(page_id)
+        storage_html = page["body"]["storage"]["value"]
+        # TODO: port ADF/storage → markdown conversion from markdown-confluence
+        return storage_html  # placeholder
+
+    def update_page(self, page_id: str, markdown_content: str) -> dict:
+        """Convert markdown to storage format and update the page."""
+        page = self.get_page(page_id)
+        current_version = page["version"]["number"]
+        title = page["title"]
+        # TODO: port markdown → ADF conversion from markdown-confluence
+        storage_value = markdown_content  # placeholder
+        payload = {
+            "version": {"number": current_version + 1},
+            "title": title,
+            "type": "page",
+            "body": {"storage": {"value": storage_value, "representation": "storage"}},
+        }
+        url = f"{self.base_url}/wiki/rest/api/content/{page_id}"
+        resp = self.session.put(url, json=payload)
+        resp.raise_for_status()
+        return resp.json()

docspan/backends/confluence/config/__init__.py

@@ -0,0 +1,21 @@
+"""
+Configuration module.
+
+This module provides functionality for loading and managing configuration
+for the markdown-confluence package.
+"""
+
+from docspan.backends.confluence.config.loader import load_config, load_config_from_dict
+from docspan.backends.confluence.config.models import (
+    ConfluenceConfig,
+    MarkdownConfluenceConfig,
+    PublishConfig,
+)
+
+__all__ = [
+    "ConfluenceConfig",
+    "PublishConfig",
+    "MarkdownConfluenceConfig",
+    "load_config",
+    "load_config_from_dict",
+]

docspan/backends/confluence/config/loader.py

@@ -0,0 +1,107 @@
+"""
+Configuration loading utilities.
+"""
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from docspan.backends.confluence.config.models import MarkdownConfluenceConfig
+from docspan.backends.confluence.config.validation import validate_config_dict
+
+logger = logging.getLogger(__name__)
+
+
+def load_config(path: Union[str, Path], allow_env_only: bool = True, folder_to_publish: Optional[str] = None, require_parent_id: bool = False) -> MarkdownConfluenceConfig:
+    """
+    Load configuration from a JSON file or environment variables.
+
+    Args:
+        path: Path to the configuration file
+        allow_env_only: Whether to allow configuration from environment variables only
+                        when config file is not found
+        folder_to_publish: Override the folder to publish in the config
+        require_parent_id: Whether to require parent_id in configuration (needed for publishing, not for crawling)
+
+    Returns:
+        Configuration object
+
+    Raises:
+        FileNotFoundError: If the file doesn't exist and allow_env_only is False
+        json.JSONDecodeError: If the file isn't valid JSON
+        ValueError: If the configuration is invalid
+    """
+    config_path = Path(path)
+    config_data = {}
+
+    if config_path.exists():
+        # Load from file
+        with open(config_path, "r", encoding="utf-8") as f:
+            config_data = json.load(f)
+    elif not allow_env_only:
+        raise FileNotFoundError(f"Configuration file not found: {path}")
+    else:
+        # Try to load configuration from environment variables
+        # This will create an empty config_data and rely on environment variables
+        # for the required configuration values
+        pass
+
+    # If folder_to_publish is provided, override the setting
+    if folder_to_publish:
+        if "publish" not in config_data:
+            config_data["publish"] = {}
+        config_data["publish"]["folder_to_publish"] = folder_to_publish
+
+    return load_config_from_dict(config_data, require_parent_id=require_parent_id)
+
+
+def load_config_from_dict(config_data: Dict[str, Any], require_parent_id: bool = False) -> MarkdownConfluenceConfig:
+    """
+    Load configuration from a dictionary.
+
+    Args:
+        config_data: Dictionary with configuration values
+        require_parent_id: Whether to require parent_id in configuration (needed for publishing, not for crawling)
+
+    Returns:
+        Configuration object
+
+    Raises:
+        ValueError: If the configuration is invalid
+    """
+    # Validate configuration structure and detect typos
+    corrected_config, validation_errors, validation_warnings = validate_config_dict(
+        config_data,
+        auto_correct=True  # Auto-correct known typos like camelCase -> snake_case
+    )
+
+    # Show warnings for auto-corrections
+    for warning in validation_warnings:
+        logger.warning(f"Configuration: {warning}")
+
+    # Raise errors if validation failed
+    if validation_errors:
+        error_msg = "Invalid configuration:\n" + "\n".join(f"  - {err}" for err in validation_errors)
+        raise ValueError(error_msg)
+
+    # Create config object with corrected data
+    config = MarkdownConfluenceConfig.from_dict(corrected_config)
+
+    # Validate required fields
+    field_errors = config.confluence.validate(require_parent_id=require_parent_id)
+    if field_errors:
+        raise ValueError(f"Invalid configuration: {', '.join(field_errors)}")
+
+    return config
+
+
+def get_api_token_from_env() -> Optional[str]:
+    """
+    Get Atlassian API token from environment variable.
+
+    Returns:
+        API token or None if not set
+    """
+    return os.environ.get("ATLASSIAN_API_TOKEN")

docspan/backends/confluence/config/models.py

@@ -0,0 +1,167 @@
+"""
+Configuration data models for markdown-confluence.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ConfluenceConfig:
+    """
+    Configuration for Confluence connection.
+
+    Attributes:
+        base_url: Base URL for Confluence instance
+        parent_id: ID of the parent page in Confluence (optional, only required for publishing)
+        username: Atlassian username
+        api_token: Atlassian API token (optional if set in environment)
+        space_key: Confluence space key (optional)
+    """
+
+    base_url: str
+    username: str
+    parent_id: Optional[str] = None
+    api_token: Optional[str] = None
+    space_key: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """
+        Post-initialization processing.
+
+        Loads API token from environment if not provided.
+        """
+        if not self.api_token:
+            self.api_token = os.environ.get("ATLASSIAN_API_TOKEN")
+
+    def validate(self, require_parent_id: bool = False) -> List[str]:
+        """
+        Validate the configuration.
+
+        Args:
+            require_parent_id: Whether to require parent_id (needed for publishing, not for crawling)
+
+        Returns:
+            List of validation errors, empty if valid
+        """
+        errors = []
+        if not self.base_url:
+            errors.append("base_url is required")
+        if require_parent_id and not self.parent_id:
+            errors.append("parent_id is required for publishing operations")
+        if not self.username:
+            errors.append("username is required")
+        if not self.api_token:
+            errors.append(
+                "api_token is required (either in config or ATLASSIAN_API_TOKEN environment variable)"
+            )
+        return errors
+
+
+@dataclass
+class PublishConfig:
+    """
+    Configuration for publishing behavior.
+
+    Attributes:
+        folder_to_publish: Folder to publish (relative to working directory)
+        use_file_path_as_title: Whether to use file path as page title
+        prepend_file_path_to_title: Whether to prepend file path to page title
+        frontmatter_from_document_start: Whether to extract frontmatter from document start
+        skip_metadata: Whether to skip adding metadata to published pages
+        resolve_relative_links: Whether to resolve relative links between documents
+        respect_link_dependencies: Whether to respect dependencies between documents when publishing
+        auto_fix_hierarchy: Whether to automatically fix page hierarchy based on directory structure
+        auto_migrate_legacy: Whether to automatically migrate legacy editor pages to new editor before publishing
+        duplicate_similarity_threshold: Threshold for considering pages as duplicates (0.0-1.0, default 0.8)
+        render_mermaid_diagrams: Whether to render mermaid diagrams as images
+        process_assets: Whether to process assets (images, diagrams) for embedding
+        ignore_patterns: List of file patterns to ignore (supports glob patterns like **/TODO.md)
+        archive_ignored: Whether to archive/delete ignored files from Confluence if they have page IDs
+        enable_sync: Whether to check for remote changes before publishing (default: True)
+        auto_resolve_conflicts: Whether to automatically resolve conflicts (default: False)
+        prefer_remote_on_conflict: When auto-resolving conflicts, prefer remote changes (default: False, prefers local)
+        default_visibility: Default visibility for pages when not specified in frontmatter ("private" or "public", optional)
+    """
+
+    folder_to_publish: str = "."
+    use_file_path_as_title: bool = False
+    prepend_file_path_to_title: bool = False
+    frontmatter_from_document_start: bool = True
+    skip_metadata: bool = False
+    resolve_relative_links: bool = True
+    respect_link_dependencies: bool = True
+    auto_fix_hierarchy: bool = True
+    auto_handle_archived: bool = True
+    auto_migrate_legacy: bool = True
+    duplicate_similarity_threshold: float = 0.8
+    render_mermaid_diagrams: bool = True
+    process_assets: bool = True
+    ignore_patterns: List[str] = field(default_factory=list)
+    archive_ignored: bool = True
+    enable_sync: bool = True
+    auto_resolve_conflicts: bool = False
+    prefer_remote_on_conflict: bool = False
+    default_visibility: Optional[str] = None
+
+
+@dataclass
+class MarkdownConfluenceConfig:
+    """
+    Complete configuration for markdown-confluence.
+
+    Attributes:
+        confluence: Confluence connection configuration
+        publish: Publishing behavior configuration
+    """
+
+    confluence: ConfluenceConfig
+    publish: PublishConfig = field(default_factory=PublishConfig)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MarkdownConfluenceConfig":
+        """
+        Create configuration from dictionary.
+
+        Args:
+            data: Dictionary with configuration values (supports both nested and flat structures)
+
+        Returns:
+            Configuration object
+        """
+        # Handle both nested structure ({"confluence": {...}, "publish": {...}})
+        # and flat structure ({"base_url": ..., "ignore_patterns": ...})
+        confluence_dict = data.get("confluence", data)
+        publish_dict = data.get("publish", data)
+
+        confluence_data = {
+            "base_url": confluence_dict.get("base_url") or confluence_dict.get("confluenceBaseUrl") or os.environ.get("CONFLUENCE_BASE_URL") or os.environ.get("CONFLUENCE_URL") or "",
+            "parent_id": confluence_dict.get("parent_id") or confluence_dict.get("confluenceParentId") or os.environ.get("CONFLUENCE_PARENT_ID") or "",
+            "username": confluence_dict.get("username") or confluence_dict.get("atlassianUserName") or os.environ.get("ATLASSIAN_USER_NAME") or os.environ.get("CONFLUENCE_USERNAME") or "",
+            "api_token": confluence_dict.get("api_token") or confluence_dict.get("atlassianApiToken"),
+            "space_key": confluence_dict.get("space_key") or confluence_dict.get("confluenceSpaceKey") or os.environ.get("CONFLUENCE_SPACE_KEY") or "",
+        }
+
+        publish_data = {
+            "folder_to_publish": publish_dict.get("folder_to_publish", publish_dict.get("folderToPublish", ".")),
+            "use_file_path_as_title": publish_dict.get("use_file_path_as_title", publish_dict.get("useFilePathAsTitle", False)),
+            "prepend_file_path_to_title": publish_dict.get("prepend_file_path_to_title", publish_dict.get("prependFilePathToTitle", False)),
+            "frontmatter_from_document_start": publish_dict.get("frontmatter_from_document_start", publish_dict.get("frontmatterFromDocumentStart", True)),
+            "skip_metadata": publish_dict.get("skip_metadata", publish_dict.get("skipMetadata", False)),
+            "resolve_relative_links": publish_dict.get("resolve_relative_links", publish_dict.get("resolveRelativeLinks", True)),
+            "respect_link_dependencies": publish_dict.get("respect_link_dependencies", publish_dict.get("respectLinkDependencies", True)),
+            "auto_fix_hierarchy": publish_dict.get("auto_fix_hierarchy", publish_dict.get("autoFixHierarchy", True)),
+            "auto_handle_archived": publish_dict.get("auto_handle_archived", publish_dict.get("autoHandleArchived", True)),
+            "auto_migrate_legacy": publish_dict.get("auto_migrate_legacy", publish_dict.get("autoMigrateLegacy", True)),
+            "duplicate_similarity_threshold": publish_dict.get("duplicate_similarity_threshold", publish_dict.get("duplicateSimilarityThreshold", 0.8)),
+            "render_mermaid_diagrams": publish_dict.get("render_mermaid_diagrams", publish_dict.get("renderMermaidDiagrams", True)),
+            "process_assets": publish_dict.get("process_assets", publish_dict.get("processAssets", True)),
+            "ignore_patterns": publish_dict.get("ignore_patterns", publish_dict.get("ignorePatterns", [])),
+            "archive_ignored": publish_dict.get("archive_ignored", publish_dict.get("archiveIgnored", True)),
+            "default_visibility": publish_dict.get("default_visibility", publish_dict.get("defaultVisibility")),
+        }
+
+        return cls(
+            confluence=ConfluenceConfig(**confluence_data), publish=PublishConfig(**publish_data)
+        )