@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/config.py

@@ -0,0 +1,215 @@
+"""Strongly-typed Confluence settings using pydantic-settings (consistent with VDS orchestrators)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from pydantic import AliasChoices, AnyHttpUrl, Field, SecretStr, ValidationError
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+)
+from vds_cli_common.env import DEFAULT_ENV_PATHS, load_shared_env
+from vds_platform_core.config import (
+    VDS_BASE_SETTINGS_CONFIG,
+    HTTPClientSettings,
+    vds_settings_customise_sources,
+)
+from vds_platform_core.credentials import resolve_secret
+from vds_platform_core.errors import SettingsError
+
+
+class ConfluenceSettings(HTTPClientSettings, BaseSettings):
+    """Strongly-typed view of the orchestrator settings."""
+
+    model_config = SettingsConfigDict(**VDS_BASE_SETTINGS_CONFIG, env_prefix="CONFLUENCE_")
+
+    # Override HTTPClientSettings retry_backoff_initial default (1.0s vs
+    # platform_core's 0.5s) and read_timeout (legacy CONFLUENCE_HTTP_TIMEOUT
+    # alias). Aliases preserve the existing env var contracts.
+    retry_backoff_initial: float = Field(default=1.0, alias="CONFLUENCE_RETRY_BACKOFF", ge=0)
+    read_timeout: float = Field(default=30.0, alias="CONFLUENCE_HTTP_TIMEOUT", ge=0)
+
+    # Backward-compat aliases for code consumers
+    @property
+    def retry_backoff_factor(self) -> float:
+        """Legacy alias for retry_backoff_initial."""
+        return self.retry_backoff_initial
+
+    @property
+    def http_timeout(self) -> float:
+        """Legacy alias for read_timeout."""
+        return self.read_timeout
+
+    # Credential fields (cross-prefix: VDS_, INTERNAL_, EXTERNAL_)
+    username: str | None = Field(default=None, alias="VDS_USERNAME")
+    password: SecretStr | None = Field(default=None, alias="VDS_PASSWORD")
+    internal_token: SecretStr | None = Field(default=None, alias="INTERNAL_CONFLUENCE_TOKEN")
+    external_token: SecretStr | None = Field(default=None, alias="EXTERNAL_CONFLUENCE_TOKEN")
+
+    # Canonical URLs
+    internal_url: AnyHttpUrl = Field(
+        default="http://confluence.digital.vn",
+        alias="CONFLUENCE_INTERNAL_URL",
+    )
+    external_url: AnyHttpUrl = Field(
+        default="http://10.254.136.35:8090",
+        alias="CONFLUENCE_EXTERNAL_URL",
+    )
+
+    # Alternate URLs accept canonical name first, legacy fallback-era names
+    # as secondary aliases (replaces the old _normalize_legacy_endpoint_aliases
+    # procedural map with a pydantic-native AliasChoices lookup).
+    external_alternate_url: AnyHttpUrl | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "CONFLUENCE_EXTERNAL_ALTERNATE_URL",
+            "CONFLUENCE_SECONDARY_EXTERNAL_URL",
+        ),
+    )
+    internal_alternate_url: AnyHttpUrl | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "CONFLUENCE_INTERNAL_ALTERNATE_URL",
+            "CONFLUENCE_INTERNAL_FALLBACK_URL",
+        ),
+    )
+
+    default_server: str = Field(default="internal", alias="CONFLUENCE_DEFAULT_SERVER")
+
+    # Note: max_retries is inherited from HTTPClientSettings with env_prefix
+    # CONFLUENCE_ → binds to CONFLUENCE_MAX_RETRIES. retry_backoff_initial and
+    # read_timeout are declared above with explicit legacy aliases.
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Delegate to platform_core helper with local DEFAULT_ENV_PATHS."""
+        return vds_settings_customise_sources(
+            settings_cls,
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+            env_paths=DEFAULT_ENV_PATHS,
+        )
+
+    def token_for(self, server: str) -> str | None:
+        server_lower = server.lower()
+        if server_lower in {"internal", "int", "main"}:
+            return resolve_secret(self.internal_token)
+        if server_lower in {"external", "ext", "outsource"}:
+            return resolve_secret(self.external_token)
+        raise ValueError(f"Unknown server '{server}'")
+
+    def url_for(self, server: str) -> AnyHttpUrl:
+        server_lower = server.lower()
+        if server_lower in {"internal", "int", "main"}:
+            return self.internal_url
+        if server_lower in {"external", "ext", "outsource"}:
+            return self.external_url
+        raise ValueError(f"Unknown server '{server}'")
+
+    def external_urls(self) -> list[AnyHttpUrl]:
+        """Return all configured external server URLs (primary first, alternate if set)."""
+        urls: list[AnyHttpUrl] = [self.external_url]
+        if self.external_alternate_url is not None:
+            urls.append(self.external_alternate_url)
+        return urls
+
+    @property
+    def default_token(self) -> str | None:
+        return self.token_for(self.default_server)
+
+    @property
+    def default_url(self) -> AnyHttpUrl:
+        return self.url_for(self.default_server)
+
+
+def load_settings(
+    *,
+    env_path: Path | None = None,
+    overrides: Mapping[str, Any] | None = None,
+    strict: bool = False,
+) -> ConfluenceSettings:
+    """Load orchestrator settings using native pydantic-settings.
+
+    Args:
+        env_path: Optional path to a specific .env file (for testing).
+                 When provided, uses custom settings source that places the
+                 env_path file BEFORE runtime env vars (preserves legacy
+                 load_shared_env(override=True) semantics).
+        overrides: Optional mapping of values to override settings.
+        strict: If True, require valid credentials (basic auth or token).
+
+    Returns:
+        ConfluenceSettings instance with loaded configuration.
+
+    Raises:
+        SettingsError: If validation fails or strict mode requirements not met.
+    """
+    load_shared_env(path=env_path)
+    try:
+        kwargs: dict[str, Any] = dict(overrides) if overrides else {}
+
+        if env_path is not None:
+            from pydantic_settings.sources import DotEnvSettingsSource
+
+            class CustomConfluenceSettings(ConfluenceSettings):
+                @classmethod
+                def settings_customise_sources(
+                    cls,
+                    settings_cls: type[BaseSettings],
+                    init_settings: PydanticBaseSettingsSource,
+                    env_settings: PydanticBaseSettingsSource,
+                    dotenv_settings: PydanticBaseSettingsSource,
+                    file_secret_settings: PydanticBaseSettingsSource,
+                ) -> tuple[PydanticBaseSettingsSource, ...]:
+                    """Custom source chain: init → custom env_path → env vars.
+
+                    env_path precedes env_settings so explicit test/override
+                    files beat ambient runtime env (preserves legacy
+                    load_shared_env(override=True) semantics).
+                    """
+                    sources: list[PydanticBaseSettingsSource] = [init_settings]
+                    if env_path.exists():
+                        sources.append(
+                            DotEnvSettingsSource(
+                                settings_cls,
+                                env_file=env_path,
+                                env_file_encoding="utf-8",
+                            )
+                        )
+                    sources.append(env_settings)
+                    return tuple(sources)
+
+            settings = CustomConfluenceSettings(**kwargs)
+        else:
+            settings = ConfluenceSettings(**kwargs)
+
+    except ValidationError as exc:
+        raise SettingsError(str(exc)) from exc
+
+    if strict:
+        has_token = bool(settings.internal_token or settings.external_token)
+        has_basic_auth = bool(settings.username and settings.password)
+        if not (has_token or has_basic_auth):
+            raise SettingsError(
+                "Missing Confluence credentials. Provide VDS_USERNAME+VDS_PASSWORD as the primary auth mechanism, "
+                "or INTERNAL_CONFLUENCE_TOKEN/EXTERNAL_CONFLUENCE_TOKEN as fallback in the shared VDS env file "
+                "(or run './scripts/worktree_uv.sh run --project vds_cli vds-cli env load')."
+            )
+
+    return settings
+
+
+__all__ = ["DEFAULT_ENV_PATHS", "ConfluenceSettings", "SettingsError", "load_settings"]

package/skills/vds-skill/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/content.py

@@ -0,0 +1,368 @@
+"""Confluence REST v1 helpers covering read and write flows."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from contextlib import ExitStack
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, BinaryIO
+
+if TYPE_CHECKING:
+    from .http import ConfluenceClient
+
+FileLike = str | Path | BinaryIO
+
+
+class ContentClient:
+    """Operations against Confluence content endpoints (REST v1)."""
+
+    def __init__(self, http_client: ConfluenceClient) -> None:
+        self._http = http_client
+
+    # ------------------------------------------------------------------
+    # Read-only endpoints
+    # ------------------------------------------------------------------
+
+    def get_page(
+        self,
+        page_id: str,
+        *,
+        expand: Iterable[str] | None = None,
+    ) -> dict[str, Any]:
+        return self._http.get_page(page_id, expand=list(expand) if expand else None)
+
+    def search_cql(
+        self,
+        cql: str,
+        *,
+        limit: int = 25,
+        start: int = 0,
+        expand: Iterable[str] | None = None,
+    ) -> dict[str, Any]:
+        return self._http.search_cql(cql, limit=limit, expand=list(expand) if expand else None, start=start)
+
+    def cql_advanced(
+        self,
+        cql: str,
+        *,
+        limit: int = 25,
+        start: int = 0,
+        expand: Iterable[str] | None = None,
+        excerpt: str | None = None,
+    ) -> dict[str, Any]:
+        return self._http.cql_advanced(
+            cql,
+            limit=limit,
+            start=start,
+            expand=list(expand) if expand else None,
+            excerpt=excerpt,
+        )
+
+    def search_by_space_and_type(
+        self,
+        *,
+        space_key: str | None = None,
+        content_type: str | None = None,
+        limit: int = 25,
+        start: int = 0,
+        expand: Iterable[str] | None = None,
+    ) -> dict[str, Any]:
+        return self._http.search_by_space_and_type(
+            space_key=space_key,
+            content_type=content_type,
+            limit=limit,
+            start=start,
+            expand=list(expand) if expand else None,
+        )
+
+    def get_child_pages(
+        self,
+        page_id: str,
+        *,
+        expand: Iterable[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get child pages of a page."""
+        return self._http.get_child_pages(page_id, expand=list(expand) if expand else None)
+
+    def get_page_labels(self, page_id: str) -> list[str]:
+        """Get label names for a page."""
+        raw = self._http.get_page_labels(page_id)
+        return [lbl.get("name", "") for lbl in raw if isinstance(lbl, dict)]
+
+    def set_page_label(self, page_id: str, label: str) -> None:
+        """Add a label to a page."""
+        self._http.set_page_label(page_id, label)
+
+    @property
+    def base_url(self) -> str:
+        """Base URL of the underlying Confluence server (no trailing slash)."""
+        return self._http.base_url
+
+    # ------------------------------------------------------------------
+    # Mutating endpoints
+    # ------------------------------------------------------------------
+
+    def create_page(
+        self,
+        *,
+        space_key: str,
+        title: str,
+        body: str,
+        parent_id: str | None = None,
+        representation: str = "storage",
+        status: str = "current",
+        notify_watchers: bool | None = None,
+    ) -> dict[str, Any]:
+        if notify_watchers:
+            raise ValueError("notify_watchers is not supported by the Confluence Server SDK; omit the flag.")
+
+        return self._http.create_page(
+            space_key,
+            title,
+            body,
+            parent_id=parent_id,
+            representation=representation,
+            status=status,
+        )
+
+    def update_page(
+        self,
+        page_id: str,
+        *,
+        title: str | None = None,
+        body: str | None = None,
+        space_key: str | None = None,
+        representation: str = "storage",
+        version: int | None = None,
+        minor_edit: bool = False,
+        message: str | None = None,
+        status: str = "current",
+        notify_watchers: bool | None = None,
+        parent_id: str | None = None,
+    ) -> dict[str, Any]:
+        if title is None and body is None:
+            raise ValueError("At least one of title/body must be provided when updating a page")
+
+        # Get current page info if needed
+        if title is None:
+            current = self.get_page(page_id, expand=["version", "space", f"body.{representation}"])
+            title = current["title"]
+        assert title is not None
+
+        if notify_watchers:
+            raise ValueError("notify_watchers is not supported by the Confluence Server SDK; omit the flag.")
+
+        return self._http.update_page(
+            page_id,
+            title,
+            body,
+            version=version,
+            representation=representation,
+            minor_edit=minor_edit,
+            version_comment=message,
+            status=status,
+            parent_id=parent_id,
+        )
+
+    def delete_page(self, page_id: str, *, status: str = "current") -> None:
+        self._http.delete_page(page_id)
+
+    def upload_attachment(
+        self,
+        page_id: str,
+        file: FileLike,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        comment: str | None = None,
+    ) -> dict[str, Any]:
+        with ExitStack() as stack:
+            stream, resolved_name = self._prepare_file(file, filename, stack)
+            # Read file content into memory for atlassian library
+            content = stream.read()
+
+            return self._http.add_attachment(
+                page_id,
+                resolved_name,
+                content,
+                content_type=content_type,
+                comment=comment,
+            )
+
+    def list_attachments(self, page_id: str, *, expand: Iterable[str] | None = None) -> dict[str, Any]:
+        """List attachments for a specific page."""
+        result = self._http.get_attachments(page_id)
+        if isinstance(result, dict):
+            return result
+        return {"results": result or []}
+
+    def add_comment(self, page_id: str, body: str, *, parent_id: str | None = None) -> dict[str, Any]:
+        """Add a storage-format comment to a page or reply to an existing comment."""
+        if not body or not body.strip():
+            raise ValueError("Comment body cannot be empty")
+        return self._http.add_comment(page_id, body, parent_id=parent_id)
+
+    def download_attachment(
+        self,
+        attachment_id: str,
+        output_path: str | Path,
+        *,
+        filename: str | None = None,
+    ) -> Path:
+        """Download an attachment by ID to a local file."""
+        content = self._http.get_attachment_content(attachment_id)
+        output = Path(output_path)
+        if output.is_dir():
+            filename = filename or f"attachment_{attachment_id}"
+            output = output / filename
+        elif filename:
+            output = output.parent / filename
+        else:
+            output.parent.mkdir(parents=True, exist_ok=True)
+
+        output.write_bytes(content)
+        return output
+
+    def update_attachment(
+        self,
+        page_id: str,
+        attachment_id: str,
+        file: FileLike,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        comment: str | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing attachment."""
+        with ExitStack() as stack:
+            stream, resolved_name = self._prepare_file(file, filename, stack)
+            content = stream.read()
+
+            return self._http.update_attachment_data(
+                page_id,
+                attachment_id,
+                resolved_name,
+                content,
+                content_type=content_type,
+                comment=comment,
+            )
+
+    def delete_attachment(
+        self,
+        page_id: str,
+        attachment_id: str | None = None,
+        *,
+        version: int | None = None,
+        filename: str | None = None,
+    ) -> None:
+        """Delete an attachment by ID or filename.
+
+        If ``filename`` is provided we delegate to the SDK's delete-by-filename helper,
+        which deletes the current attachment (all versions when ``version`` is None).
+        Otherwise we fall back to deleting by attachment ID/version.
+        """
+
+        if filename:
+            self._http.delete_attachment(page_id, filename, version=version)
+            return
+
+        if not attachment_id:
+            raise ValueError("Provide attachment ID or --filename for deletion")
+
+        self._http.delete_attachment_by_id(page_id, attachment_id, version=version)
+
+    def move_page(
+        self,
+        page_id: str,
+        target_title: str,
+        position: str = "append",
+        *,
+        space_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Move a page to a new location under the target page."""
+        return self._http.move_page(page_id, target_title, position=position, space_key=space_key)
+
+    # ------------------------------------------------------------------
+    # Template operations
+    # ------------------------------------------------------------------
+
+    def list_templates(self, space_key: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if space_key:
+            params["spaceKey"] = space_key
+        response = self._http.request("GET", "/rest/api/template", params=params)
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"results": payload}
+
+    def create_template(
+        self,
+        *,
+        name: str,
+        body: str,
+        template_type: str = "page",
+        space_key: str | None = None,
+        description: str | None = None,
+        representation: str = "storage",
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": name,
+            "body": {"value": body, "representation": representation},
+            "templateType": template_type,
+        }
+        if space_key:
+            payload["space"] = {"key": space_key}
+        if description:
+            payload["description"] = description
+        response = self._http.request("POST", "/rest/api/template", json=payload)
+        return response.json()
+
+    def get_template(self, template_id: str) -> dict[str, Any]:
+        response = self._http.request("GET", f"/rest/api/template/{template_id}")
+        return response.json()
+
+    def update_template(
+        self,
+        template_id: str,
+        *,
+        name: str | None = None,
+        body: str | None = None,
+        description: str | None = None,
+        representation: str = "storage",
+        template_type: str | None = None,
+    ) -> dict[str, Any]:
+        existing = self.get_template(template_id)
+        payload = {
+            "name": name or existing.get("name"),
+            "templateType": template_type or existing.get("templateType", "page"),
+            "description": description or existing.get("description"),
+            "body": (body and {"value": body, "representation": representation}) or existing.get("body"),
+        }
+        response = self._http.request("PUT", f"/rest/api/template/{template_id}", json=payload)
+        return response.json()
+
+    def delete_template(self, template_id: str) -> None:
+        self._http.request("DELETE", f"/rest/api/template/{template_id}")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _prepare_file(
+        self,
+        file: FileLike,
+        filename: str | None,
+        stack: ExitStack,
+    ) -> tuple[BinaryIO, str]:
+        if isinstance(file, (str, Path)):
+            path = Path(file)
+            stream = stack.enter_context(path.open("rb"))
+            name = filename or path.name
+            return stream, name
+
+        stream = file  # BinaryIO
+        inferred_name = getattr(stream, "name", None)
+        resolved = filename or (Path(inferred_name).name if inferred_name else "attachment")
+        return stream, resolved
+
+
+__all__ = ["ContentClient"]