@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/config.py

@@ -0,0 +1,175 @@
+"""Configuration loading utilities for the Confluence orchestrator."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import AnyHttpUrl, BaseModel, Field, ValidationError
+
+_PROJECT_ROOT = Path(__file__).resolve().parents[3]
+_SCRIPTS_DIR = _PROJECT_ROOT.parent
+
+DEFAULT_ENV_PATHS = (
+    Path.home() / ".vds" / ".env",
+    _SCRIPTS_DIR / ".env",
+)
+
+_REQUIRED_KEYS: tuple[str, ...] = (
+    "VDS_USERNAME",
+    "VDS_PASSWORD",
+    "INTERNAL_CONFLUENCE_TOKEN",
+    "EXTERNAL_CONFLUENCE_TOKEN",
+)
+
+_OPTIONAL_KEYS: tuple[str, ...] = (
+    "CONFLUENCE_DEFAULT_SERVER",
+    "CONFLUENCE_INTERNAL_URL",
+    "CONFLUENCE_EXTERNAL_URL",
+    "CONFLUENCE_MAX_RETRIES",
+    "CONFLUENCE_RETRY_BACKOFF",
+)
+
+
+class SettingsError(RuntimeError):
+    """Raised when the environment configuration cannot be loaded."""
+
+
+class ConfluenceSettings(BaseModel):
+    """Strongly-typed view of the orchestrator settings."""
+
+    username: str | None = Field(default=None, alias="VDS_USERNAME")
+    password: str | None = Field(default=None, alias="VDS_PASSWORD")
+
+    internal_token: str | None = Field(default=None, alias="INTERNAL_CONFLUENCE_TOKEN")
+    external_token: str | None = Field(default=None, alias="EXTERNAL_CONFLUENCE_TOKEN")
+
+    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",
+    )
+
+    default_server: str = Field(default="internal", alias="CONFLUENCE_DEFAULT_SERVER")
+
+    # Retry configuration
+    max_retries: int = Field(default=3, alias="CONFLUENCE_MAX_RETRIES")
+    retry_backoff_factor: float = Field(default=1.0, alias="CONFLUENCE_RETRY_BACKOFF")
+
+    class Config:
+        populate_by_name = True
+
+    def token_for(self, server: str) -> str | None:
+        server_lower = server.lower()
+        if server_lower in {"internal", "int", "main"}:
+            return self.internal_token
+        if server_lower in {"external", "ext", "outsource"}:
+            return 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}'")
+
+    @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)
+
+
+@dataclass(frozen=True)
+class EnvSnapshot:
+    """A snapshot of relevant environment variables."""
+
+    values: Mapping[str, str]
+    source: Path | str | None
+
+
+def _parse_env_file(env_path: Path) -> dict[str, str]:
+    if not env_path.exists():
+        return {}
+
+    result: dict[str, str] = {}
+    for raw_line in env_path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, raw_value = line.split("=", 1)
+        key = key.strip()
+        value = raw_value.strip().strip('"').strip("'")
+        if key:
+            result[key] = value
+    return result
+
+
+def _merge_env_sources(*snapshots: EnvSnapshot) -> dict[str, str]:
+    merged: dict[str, str] = {}
+    for snapshot in snapshots:
+        merged.update(snapshot.values)
+    return merged
+
+
+def _filter_keys(source: Mapping[str, str]) -> dict[str, str]:
+    relevant_keys = set(_REQUIRED_KEYS + _OPTIONAL_KEYS)
+    return {key: value for key, value in source.items() if key in relevant_keys}
+
+
+def _resolve_env_paths(env_path: Path | None) -> Iterable[Path]:
+    if env_path is not None:
+        return (env_path,)
+    return DEFAULT_ENV_PATHS
+
+
+def load_settings(
+    *,
+    env_path: Path | None = None,
+    overrides: Mapping[str, str] | None = None,
+    strict: bool = False,
+) -> ConfluenceSettings:
+    """Load orchestrator settings from the environment and optional .env file."""
+
+    snapshots = []
+    for candidate in _resolve_env_paths(env_path):
+        snapshots.append(
+            EnvSnapshot(
+                values=_filter_keys(_parse_env_file(candidate)), source=candidate if candidate.exists() else None
+            )
+        )
+
+    snapshots.append(EnvSnapshot(values=_filter_keys(os.environ), source="os.environ"))
+
+    if overrides:
+        snapshots.append(EnvSnapshot(values=_filter_keys(overrides), source="overrides"))
+
+    merged = _merge_env_sources(*snapshots)
+
+    try:
+        settings = ConfluenceSettings.model_validate(merged)
+    except ValidationError as exc:
+        raise SettingsError(str(exc)) from exc
+
+    if strict:
+        has_token = bool(settings.internal_token or settings.external_token)
+        if not has_token:
+            raise SettingsError(
+                "Missing Confluence bearer tokens. Run 'uv run --project vds_cli vds-cli env load' before invoking the CLI."
+            )
+
+    return settings
+
+
+__all__ = ["ConfluenceSettings", "SettingsError", "load_settings", "DEFAULT_ENV_PATHS"]

package/tools/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/content.py

@@ -0,0 +1,290 @@
+"""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 Any, BinaryIO
+
+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)
+
+    # ------------------------------------------------------------------
+    # 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,
+    ) -> 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"]
+
+        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,
+        )
+
+    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 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)
+
+    # ------------------------------------------------------------------
+    # 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"]

package/tools/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/content_v2.py

@@ -0,0 +1,94 @@
+"""Confluence Cloud REST v2 client utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from .http import ConfluenceClient
+
+
+class ContentClientV2:
+    """Minimal adapter for Confluence Cloud REST v2 endpoints."""
+
+    def __init__(self, http_client: ConfluenceClient) -> None:
+        self._http = http_client
+
+    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,
+        cursor: str | None = None,
+        expand: Iterable[str] | None = None,
+    ) -> dict[str, Any]:
+        return self._http.search_cql(cql, limit=limit, expand=list(expand) if expand else None)
+
+    def list_templates(
+        self,
+        space_key: str | None = None,
+        limit: int = 25,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        params = {"limit": limit}
+        if space_key:
+            params["spaceKey"] = space_key
+        if cursor:
+            params["cursor"] = cursor
+        response = self._http.request("GET", "/wiki/api/v2/content-templates", params=params)
+        return response.json()
+
+    def get_content(
+        self,
+        page_id: str,
+        *,
+        expand: Iterable[str] | None = None,
+        format: str | None = None,
+    ) -> dict[str, Any]:
+        """Get content by page ID - alias for get_page for compatibility."""
+        return self.get_page(page_id, expand=expand)
+
+    def list_attachments(self, page_id: str, *, expand: Iterable[str] | None = None) -> dict[str, Any]:
+        """List attachments for a specific page."""
+        params: dict[str, Any] = {}
+        if expand:
+            params["expand"] = ",".join(expand)
+        response = self._http.request("GET", f"/wiki/api/v2/pages/{page_id}/attachments", params=params)
+        return response.json()
+
+    def upload_attachment(
+        self, page_id: str, file, filename: str | None = None, comment: str | None = None
+    ) -> dict[str, Any]:
+        """Upload attachment to a page using Confluence v2 API."""
+        from pathlib import Path
+
+        if isinstance(file, (str, Path)):
+            file_path = Path(file)
+            if not file_path.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+            filename = filename or file_path.name
+            with open(file_path, "rb") as f:
+                files = {"file": (filename, f, "application/octet-stream")}
+                data = {"comment": comment} if comment else None
+                response = self._http.request(
+                    "POST", f"/wiki/api/v2/pages/{page_id}/attachments", files=files, data=data
+                )
+                return response.json()
+        else:
+            # Handle file-like objects
+            filename = filename or "upload"
+            files = {"file": (filename, file, "application/octet-stream")}
+            data = {"comment": comment} if comment else None
+            response = self._http.request("POST", f"/wiki/api/v2/pages/{page_id}/attachments", files=files, data=data)
+            return response.json()
+
+
+__all__ = ["ContentClientV2"]